APLSV Operations Guide IBM SH20-1461-0

8/2/2019 APLSV Operations Guide IBM SH20-1461-0

1/97

SYSTEMS

SH20-11-161-0 .:

APL SHARED VARIABLES (APLSV)OPERAT!ONS GUIDEPr-ogr arrm l nz RPQ WE1l91Program Number 5799-AJF

This; maru a l co rt a l n s theinformation ne ccs s a r y t : insta l l ,operate and main_ain and TSIO.TSIO is an IBM-supplied auxiliaryprocessor which provides access toOperating System data se ts from APLSVterminals. The use of TSIO isoptional.

The prog r amm i ng RPrl des c r i hed inth is manual, and ,'11 l lcensedmaterials available or areprovided by IBM on a spe ial quotationbasis only, unrler th e of theLicense Agreement for IBM ProgramProducts. Your local IBM branchoffice can advise you regarding thespecial quotation and orderingprocedures

.@Copyright IBM Corporation, IG73.


2/97

CONTENTS

iNTRODUCTIONSystem DescriptionProgramming SystemsSystem RequirementsCompatibll ity with APL\360

PART I: APLSV AND TSIO INSTALLATIONPre-Instal lat ion PlanningSpecifying Installation-Dependent Instal l ing APLSVConversion from APL\360APLSV Instal lat ion Macros

PART I I : APLSV OPERATIONIntroductionStarting APLSVReplying to APLSV Startup MessagesThe Recording TerminalTermlnating APLSVRecording Terminal Messages . .Privileged APLSV System CommandsUse of Non-Privileged CommandsPasswordsThe APLSV Operator's Workspace, OPFNSAPLSV Operat ing Suggest ions

PART I I I: TSIO OPERATIONCommunicating with TSIOMaximum Number of Concurrent UsersThe TSIO Operator Funct ions Workspace, TSIOPSTSIO User VolumesUser Level DiscriminantsIni t ia l izat ion of TSIOTSIO System Error Return Codes

PART IV: APLSV UTILITY OPERATION

113345710131617

202020212223232426272736394041414243444546

Introduction 46Terminology 46Definitions of APLSV Util i ty. Operations 47Executing APLSV Util i ty Operations 53Util i ty Operation Notes 55Adding Instal lat ion Billing Routines to the APLSV Uti l i ty 57


3/97

\RT V: AUXILIARY PROCESSORSIntroductionControl BlocksReturn CodesEstablishing a Connection with SVPEstablishing a Shared VariableTerminating a ConnectionTerminating a SessionAccess ControlData TransferLink Editing Auxll iary User of the Test M0nltor

APPENDIX A: SYSTEM MESSAGESTSlO MessagesIni t ia l Program Load MessagesAPLSV Supervisor MessagesAPLSV ln i t i i l iza t ion MessagesAPLSV Uti l i ty Messages

APPENDIX B: WORKSPACES DISTRIBUTED WITH APLSVNew Workspaces for Users . User Workspaces Distributed in Earlier APL ReleasesWorkspaces for the System Operator

APPENDIX C: THE PRIMES UP TO 50

FIGURESFIGURE 1: Sample APLSV Insta l la t ionFIGURE 2: APLSV System Data SetsFIGURE 3: Sample Startup ReplyTABLE 1: APLSV Util i ty Operations

616161626264 e6R69696973747575777880. 81

88919294

61922

.,


4/97

-1 -

IONAPLSV is a successor to APL\360-0S (Program Number 5734-XM6).ovides an enhanced language, access to Operating System f i les

data through the auxiliary processor T510, and, support ofVSl and OS/VS2 rather than MFT and APLSV, like APL\360, isI interactive system oesigned to give rapid response to a large,umber of terminal users.

APLSV consists of three main programsro The APLSV interpreter , which executes APL functions.o The Shared-Variable Processor, manages shared variables.o The APLSV supervisor, which manages sharinR.Certain service routines are also provided:o An auxiliary processor, TSIO, which provides a shared-variable 'interface to the Operating System.o A startup and,ini t ia l ization routine.o The APLSV Util i ty , for l ibrary maintenance.

In addit ion, APLSV workspaces are provided in the APLSVdistribution library to i l lust ra te the use of new primitives,system variables and funcLions, and shared variables., QQg[110g fb[lgr12112 APlSVoperation is controlled byth e APLSV supervisor program which uses standard Opr.rating Systemfaci l i t ies for all services from the Operating System. A singletype-l SVC is used for communication between the APL Interpreterand supervisor, and between a l l programs using sha red variables andthe shared variable processor.

When APLSV is started, a monitoruses either prespecified parameters oroperator to determine the programs to beof storage to the various routines. 'program is loaded whichconsole input from theloaded and the allocation

The APLSV interpreter, supervisor, shared-v .r I ab l e processor,and the in i t ia l iza t ion routine are th en loaded, and control istransferred to the in i t ia l izat ion routine which opens th e swap andl ibrary f i les , formats the swap f i le , and in i t ia l izes varioustables associated with control and terminal Whenin i t ia l iza t ion is complete, a timer event is enqueued and control' i s returned to the monitor, which remains inactive unless someevent occurs which requir?s i ts action.

The expiration of the Ini t ia l timer event causes the APLSVsupervisor to be activated, and i t proceeds to , in i t ia l izetypewriter buffers, the in i t ia l izat ion program, and enablethe terminal ports. For the dura tion o f the operating period, th esystem is driven entirely by Interrupts passed to i t by th eOperating System supervisor, from following sources:


5/97

-2 - . 'Multiplexor Channel appropriate action is taken onth e condition. an incoming call is answered and inputhas heen received, the sign-on process is ini t ia ted byreading a user directory and passing control to the APLinterpreter. The interpreter determines subseqUEnt action,and issues requests to the supervisor for output oradditional input as necessary.

Selector Channel - If an error has occurred, Operating Systemerror recovery is invoked. If an I/O . ransfer has completed,the supervisor scheduling routine is nr t I f l e d ,supe r v lsor call - signals a request from the APLSV l rt e r p r e t e rfor 1 ibrary access, terminal I/O, or mi scellaneous service.Interval timer - signals that some is due. -Intervalevents include quantum end for time sharing, timedmultiplexor retr ies , prior i ty switchlng, and user-requesteddelays.

Program checks - in supervisortermination; in problem sta te ,interpreter for analysis.sta te , resul tare passed to in APLSVth e APLSV

Virtual memory support is enahled when APLSV has no t beenini t ia ted with ADDRSPC=REAL. in i t i a l iza t ion, the storage-allocated to the APLSV supervisor ann to terminal hu:-fers is lockedin ' real core. All code ope r a t es ; in relocation mode, and twoadditional supervisory routines a re enab led:A selector channel page-fix appendage which passes a l i s t ofaddresses to be temporarily fixed fo r an I/O t ransfer .

ccw r elocat ion rou tines, which t ranslate multiplexor channelCCWs so that they contain real storag0 addresses during I/Ot ransfer , and contain virtual addresses when the CCW chainhas completed and is to be analysed.The shared-variable processor operates as an independentsubsystem. It consists of approximately 4,oro bytes of code and anarbitrary amount of s to rage ( speci fi ed when - PLSV is started) usedfor tables and for storing shared variabl 5 . The processor isdesigned and implemented as i t wer an independent deviceanalogous to a channel or a storage faci l i v, An interface andassociated protocol for submitting requests s defined, and can beaccessed through the APLSV SVC u,ing assembly-languagemacros provided with th e distributed system.The APLSV ut i l i ty program provides a variety of accountingand l ibrary maintenance functions, and in addition, providesconversion between APL/360 workspaces and APLSV workspaces.TSIO is an auxiliary processor which uses standard oneratlngsystem routines for device and da ta - se t a ll oca ti on , and BSAM and

BDAM for fi le access. A simple security scheme is provided.


6/97

i

o The supported host operating systems are OS/VSl and OS/VS2.o The following programs are required for insta l la t ion:Assembler, Linkage Editor, Uti l i t ies .o APLSV is w ritten ent i rely in Assembler Language.o APLSV manages data as follow s:Terminals: APLSV provides the same te rm inal suppo rt as APL\360,using i t s own access method.Swapping and Library Access: EXCPo TSIO manages data as follows:APLSV user I/O: BSAN, BDNl. (Blocked 'se que n t i a l data sets aresupported.)

Logging data set : QSAM The System/3jO configuration chosen must include the considerationsbelow:Selector channel devices supported for swapping and l ibrarystorage: 2314, 2319, 3330. An arbi t rary number of devices maybe used for swapping; these need not be of the same type. Amaximum of 32 l ibrary extents; each of which may be an ent iremodule, is supported; l ibrary devices must be of the same type.A minimum of one swap data set and one l ibrary data set isrequired.Storage required: The recommended minimum OS/VSl part i t ion orOS/VS2 region for a ten-port APLSV system is 212k bytes. Thisincludes space for ten terminal control and areas ofapproximately 400 bytes each, the minimum of two worKspace slotsa t the APL\360 standard size of 36000 bytes, and a 10000-hyte

variable storage. A separate par t i t ion or region of 80kbytes is requ ired for TSIO. Since part i t ions and regions areactually allocated in multiples of 64k bytes, the minimum virtualstorage requirements are 256k bytes and 128k bytes for APLSV andTSIO respectively. The recommended rl n lmum amount of r e a lstorage which should be available when APLSV is operating is100,000 bytes, assuming ten or fewer te rm inals a re attached.Transmisslon Control Units supported: 2702, 2703 orwith IBM line control. A minimum of one l inerequired.

equi valent,position isTerminal devices supported: rBM 1050, 2740 model 1, 2741, orequivalent. A mInimum of one such :which must have aninterrupt feature) is required.A minimum of one tape drive is required for insta l la t ion anrll ibrary maintenance.


7/97

\

-4- . wItb APl\360

APL\360 programs will operate correct1y in APLSV except forminor changes in residue, oecode, and changes in l i tera l input anrloutput. Consult the APLSV User's Manual, SH20-1460, for detai ls .

When APLSV is ins tal led, APL\360 l ibrar ies must be convertedby dumping them to tape with the APL\360 Util i ty , reallocatin8 thel ibrary data sets , and then usIng the APLSV Util i ty to create APLSVl ibrar ies from the APL\360 dump tape.The APLSV Util i ty program conversion between APL\360w0rkspaces and the APLSV workspace format. Although APLSVworkspaces may be converted to the APL\360 format, functions whichcontain advanced language features as execute, format, andsystem functions and variables, will riot operate in APL\360.

. .


8/97

-5 -:PART

APLSV AND T510 INSTALLATION

basic machine-readable material for APLSV consists ofthree tdpe f i les:o The APLSV d is tr ibu ti on l ib ra ry which contains a model APLSV userdirectory and a variety of APLSV workspaces. A l i s t ing of theworkspaces supplied is given in Appendix B of this manual.o APLSVS.GENL1B, a part i t ioned data set containing the macro l ibrary.o APLSVS.PUNCH, a part i t ioned data se t conta"ining the object-modulel ibrary. The modules in th is lib ra ry are . linkedited with a

locally assembled punch module to produce the various APLSV loadmodules.The must determine the space neces sa ry for andal locate the APLSV l ibrary and swap data se t s , as described below.APLSVand TSIO can then be insta l led by copying the ins tal lat ionmacro l ibrary to disk, then using i t to assemble a set ofconfiguration macros. This assembly punches four jobs:

o An ins tal la t ion job . .o JCL to execute th e APLSV Util i tyo JCL to in i t ia te APLSVo JCL to . in i t ia te TSIO

The ins tal la t ion job constructs an APLSV system ta ilored to aparticular ins tal la t ion and modifies the OS/VSl or VS2 system toaccept i t by adding one type-l user SVC. The remaining three jobswill only run with the modified OS/VSl or VS2 nucleus, which willbe a secondary nucleus unti l renamed by the ins ta l le r .The APLSV Uti l i ty is used during the i rs ta l la t ion process toin i t ia l ize the APLSV user l ibrary data sets , and ei ther to restorethe APLSV d is tr ibu ti on l ib ra ry to them or to :onvert and restore anexisting APl\360 ut i l i ty dump tape to them.


9/97

Figure I , immediately follows, represents a. sampleAPLSV instal lat ion job. The descriPtion of APLSV instal lat ionwhich follows refers to this example.IIAPLALLOC JOB (ACCOUNT),NAME11* ALLOCATE APLSV SWAP AND LIBRARY DATA SRTSII EXEC PGM=IEFBR14IIAPLDIBO DD DSN=APLSVS. APLLIBO.II SPACE=(CYL,(SO),.CONTIG),DISP=(NEW,KEEP).II UNIT=2314.VOL=SER=APLPAKI DD DSN=APLSVS .APLSWAPO. ,II SPACE=(CYL,(7) CONTIG),DISP=(NEW.KEEP).II UNIT-'2314.VOL=SE:R=APDPAKIIAPLSVGEN JOb (ACCOUNT).NAMEII EXEC PGM=IEHMOVE11* RESTORE APLSV MACRO LIBRARY TO DISKIISYSUTl DD UNIT=2314,SPACE=(CYL,(4.4))IISYSPRINT DD SYSOUT=AliT DD UNIT=(2400.,DEFER),LABEL=( ,NL),DISP=OLD,VOL=SER=APLSVT,II DSN=APLSVT,DCB=(BLKSIZE=800,LRECL=80,RECFM=FB)liD DD IISYSIN DD *COpy PDS=APLSVS.GENLIB,FROM=2400=(APLSVT,4),IO=2314=APLPAK.FROMDD=T1* .IIASMGEN EXEC ASMFC,PARM=DECK11* GENERATE INSTALLATION AND RUlJl;DECKSIISYSLIB DD DSN=APLSVS.GENLIB,VOL=SER=APLPAK,UNIT=2314IISYSIN DD DATA** SPECIFICATION MACROS* APLSWAP UNIT=2314,VOL=APLPAKAPLLIBUNIT=2314,VOL=APLPAK.DIRS=2. APL UNIT=2314.VOL=APLPAKAPLGEN UNIT=2314.VOL=APLPAKTSIO UNIT=2314.VOL=APLPAK 'APL SVC=255.JOBNAME=APLSYSRES UNIT=2314. VOL=SYSPAK .'i.'YPE=VS1R2WORK UNIT=231 LtTAPE UNIT=2400-3SYSRES MACBLK=3520APLPORT UNIT='31'.TYPE=2741APLPORT UNIT='33' .TYPE=TS41

APLPORT UNIT=X'30'.TYPE=1050APLPORT UNIT=X'40'.TYPE=2741APLPORT UNIT=(X'lE'.X'23'),TYPE=AMBIG


10/97

-7-PRODUCTION MACROS

REPRO/APLINST JOB (ACCOUNT),NAMEINSTALLREPRO/APLUTIL JOB (ACCOUNT),NAME,TYPRUN=HOLDRUN UTILITYREPRO/APLSV JOB (ACCOUNT).NAME.TYPRUN=HOLDRUN APLREPRO/APLTS10 JOB (ACCOUNT) NAME ,TYPERUN=HOLDRUN 7'S10END*

FIGURE 1: SAMPLE APLSV INSTALLATION Elgnnlnglne type-1 SVC number must be reserved by the SVCTABLEiystem-generation macro when generating the OS/VSl or VS2 system is to host APLSV. APLSV places no restr ic t ions on the SVClumber to be used.:he multiplexor channel addres,es of the l ines to be used for,PLSV terminals and the kind of tra nsm ission control unitnstal led must be determined. If the control unit is an IBM1702, the correct SAD command for the l ine adapters to be used'o r APLSV terminal ports must be determined. If any terminals're connected direct ly to the control unit (for example, by an8M Limited Distance Four-Wire Modem) the kinds of terminals'us t be known.:he size of the APLSV user l ibrary and swap data sets must determined.Figure ' 2, at the end of the APLSV Instal lat ion secti6n,i l lus t ra tes the data sets required to ins tal l and r un each APLSVsystem. The direct-access volumes which w ill contain these datasets must be chosen. Data sets specified in Figure 2 asallocation type 3 are allocated during the insta l la t ion job.If i t becomes necessary to rerun the insta l la t ion job, these.data sets must be deleted f i r s t .The APLSV user l ibrary data sets must be allocated before th el ibrary maintenance ut i l i ty is run. The APLSV swap data setmust be allocated before theAPLSV terminal system .can be run.'

.l, .


11/97

-8":

The unit of storage allocated to . APLSV users is a which contains defined functions and variables. Eachuser may save wo rkspaces in a private 11l2IElLY, identif ied by thesign-on account number, and each active user has an containing functions and variables currently beingmanipulated. The workspace size, FSSIZE, is the amount of activestorage tha t an APLSV user has available to him. A small number ofar ea s (s lo t s) , each of WSSIZE' bytes, is reserved in the APLSVpar t i t ion or region to contain active workspaces. The number ofslots is usually much smaller than the number of access ports .APLSV t ransfers workspaces between .the slots in the reg i on "and aswapping data set as necessary. The minimUM permissible number ofslots is two. The number of slots is specified during insta l la t ionby the SLOTS parameter of the APL macro, anrl can be varied APLSV s tar tup i f necessary.

In order to aid in the t ransfer of "workspaces between APLsystems, a standard workspace size Is es t ab l l shed . All APLworkspaces dis t r ibuted by IBM are operable In a system which hasbeen ins tal led with a workspace size equal to or greater than th estandard. A " workspace of 36k bytes was the standard size forAPL\360 but the standard size of th e APLSV system'sworkspace is 64400 bytes, representing 5 tracks of 3330 storage.In general, an increase in the workspace size results in anincrease in the size of APL variables that can be manipulated, at acost of increased storage requirements and an increase in the timerequired for swapping operations. The workspace size must notexceed the amount of real storage -wh l ch wi 11 be avai l a b l e fo r pagereplacement when APLSV is running.

ED9 Q! A minimum of two data sets is requiredby APLSV. The f i r s t of these, a data set , is used to hold th eactive workspaces of users while other workspaces are beingprocessed in the region or par t l t ion. The second is a dataset and is used to store and workspaces saved byAPLSV users in private and public l ibrar ies . The APLSV userdirector ies contain a ll of the accounting in fo rmation for the usersof the system and th e names and f i le locations of all savedworkspaces. Two copies of each directory are maintained at thebeginning of the f i r s t l ibrary data set .APLSV can he configured to have up to 10 swap data sets andup to 32 l ibrary data sets

. Once the workspace size has been decided and th e numher ofports is known, the swap data se t requirements can be calculated.Space is required in the swap f i le for three workspaces thanthe number of ports configured. Workspaces are written Inhal f r t r a ck blocks, 3520 bytes per" block for the 2:,14 and 6440 bytesper block for the 3330. The number of required perworkspace is the workspace size divided by the n-Imber of bytes perblock, rounded up .


12/97

. ,

-9-For example, the 64400 byte standard workspace used with 2314disk on a system with ten access ports requires or 13 x19 = 247 blocks.cr is the APL symbol meaning "round up").

This' is 123.5 t racks, or something less than 7 cylinders of 2314space.The requirements for the APLSV user l ibrar ies are moredi f f icu l t to estimate, since workspaces saved by in thel ibrar ies will occupy only as many blocks as they require, and willvary in size from a of 3000 bytes to the full workspacesize. In practice, l ibrary workspaces tend to be sl ight ly morethan half ful l , and th e numper of workspaces per user willgenerally increase to meet th e l imit imposed by the system If a new system is being generated, of one-half

the workspace size per user is a reasonable estimate. If anexisting APL\360 system is being replaced, the current APL l ibrarydata set sizes can be used. In arldition to user l ibrar ies, th ef i r s t l ibrary data se t contains the APLSV user director ies , eachone of which requires two times the next even number of blocksgreater than or equal to that required for a full workspace.Thus, i f the 10 port system above had 2 director ies , which isthe minimum number allowed, the f i r s t l ibrary extent would requirea t 1east2X2 x20 blocks, or 40 The number of user director ies required for a new system can

be estimated from the workspace size ann th e expected number ofenrolled users, that is , the number of users who are permittedaccess to the system.Multiply the number of users by 400 and divide by theworkspace size minus an overhead of 10000, then round up to th enext prime.If one hundred users were allowed to access the ten port 2314system mentioned above,r (400Xl00)t(64400-10000} or ro .8

In other words, 1 directory is required, so the minimum directoryallotment is suff ic ient .

If an existing APL\360 system is being renlaced, simply copythe number of directories i t has.In either case, note tha t because the method used forassigning users to director ies requires that the number ofdirectories be a prime number, the next prime larger than or equalto the number calculated or copied above should he userl. Theprimes up to 50, and the APL program which produced them, are given.in a ppendixC .


13/97

-10-An in i t ia l estimate of 3x1000r 300 saved workspaces of about10 blocks each gives a total l ibrary space requirement ofapproximately 80 cylinders -- 40 tracks for director!es, plus 1500tracks for saved workspaces. Should i t la ter become necessary, th eAPLSV Uti l i ty can be used to increase the size and number of the

APLSV l ibrary data sets .In summary, the example ten port 2314 system requires 7cylinders for the swap data set and 80 cylinders for the APLSV USArl ibrary. The two data se ts must each be allocated in a singlecontiguous extent . The job shown below performs this allocation.

/IAPLALLOC JOB (ACCOUNT),NAMEII EXEC PGM=IEFBRI4IIAPLLIBO DD II II UNIT=2314,VOl=SER=APLPAKIIAPLSWAPO DO DSN=APlSVS.APLSWAPO, .II SPACE=(CYL,(7)"CONTIG),DISP=(NEW,KEEP),II UNIT=2314,VOl=SER=APlPAK

Figure 2 indicates that all th e data sets required forgeneration and use of the 10 port APlSV system will easily f i t onone 2314, so. APLPAK will be th e volume serial supplied to theins tal la t ion assembly.If the number of tracks required for swap or l ibrariesexceeds the capacity of a single direc t access volume, additionaldata sets on other volumes must be specified. Each data se t usedmust consis t of a single continuous extent .

lnSlgllgllQn-QgQgnggnl EgrgmglgrSThe APLSV ins tal la t ion is specified by a sequence ins tal la t ion micro instructions which are summarized at the end ofPart I . The specif ication macro instructions may be assembled inany order, but must precede the production macros which actuallyproduce the neces sa ry control in the Assembler SYSPUNCHdata set . There is no requirement that all of the parameter s for amacro be on a ca l l . For example,APL UNIT=2314APL SVC=255

is equivalent toAPL SVC=255,UN1T=2314Referring to the sample ins tal lat ion contained in Figure 1,and examining thp. macros one at a time:APLSWAP

specifies tha t the APlSV swap data se t will be on th e 2314 volumeAPLPAK.


14/97

-11-APLLIB UNIT=2314,VOL=APLPAK,D1RS=2

specifies that the APLSV user l ibrary will also be on APLPAK, andwill contain 2 user direc tor ies . If the user l ibraries are to becontained on several volumes, each volume must be specified on anAPLLIB statement. Note that .the data set on the volumespecified must be at least large enough to contain the userdirec tor ies .

APL UNIT=2314,VOL=APLPAKindicates that th e APLSV load-module data set should be bui l t onAPLPAK. The default WSSIZE of 64400 will be used, and thisparameter is not expl ici t ly specified.

APLGEN UNIT=2314,VOL=APLPAKindicates that the generation macro data se t has been restored toAPLPAK, and also that the punch-module data se t will be buil tthere. TSIO UNIT=2314,VOL=APLPAK.'indicates that the TSIO catalog and the TSIO data set which willcontaIn a table of valid users should also be allocated on APLPAKby the instal lat ion job.

Assuming that the host system is OS/VSl release 2 and thatthe system generation has proNided 255 as an type 1 SVC,that th e characters lAPL 1 wi i ( be used as the ini t ia l characters ofacceptable APLSV, Uti l i ty , and TSIO job name';, and that SYSPAK isth e volume serial number of the volume containing SYS1.NUCLEUS, theAPLSV instal lat ion assembly is supplied with two macros whichcontain th e fo llowing:

APL SVC=255,JOBNAME=APLSYSRES UNIT=2314,VOL=SYSPAK,TYPE=VSIR2The work f i les could all be allocated on a specific VOlume,for instance WORKOl, by specifyingWORK UNIT=2314,VOL=WORKOl

However, in Figure 1 the allocation of these temporary 'data sets is to system by specifying

WORK UNIT=2314The tape unit which will be used during APLSV instal lat ion isspecifiedTAPE UNIT=2400-3


15/97

-12-Finally, th e BLKSIZE parameter for the system macro l ibrary,SYSl.MACLIB, is necessary, so that the system macro l ibrary can becatenated with th e APLSV macro l ibrary for the instal lat ion job.If not known, the blocksize of the system macro l ibrary can obtained from th e LISTVTOC FORMAT operation of the OS/VS ut i l i tyIEHLIST.SYSRES MACBLK=3520

The instal lat ion procedure expects the system macro l ibrary to becataloged. I t does not a l t e r th e l ibrary.Suppose the terminal configuration of th e lO-port systRmconsists of six dial-up l ines and four hard-wired terminals: two27415, a 1050 system, and a 2740-1; with the following :liultiplexorchannel addresses:1E,lF,20,21,22,2330313340

The six d ia l-u p l inesThe 1050 system. .One 2741The otherThe 274.0-1Suppose further that of the 27415, the one on port 33 prints APLproperly with the 988 typing element and th e one on port 31 withthe 987. Then the 2741 which uses the 987 i s a Correspondence2741.

APLPORT UNIT=X'31',TYPE=2741.. .The is a PTTC/BCD 2741, coded

APLPORT UNIT=X'33',TYPE=TS41The 2740, which uses the 987 element, is coded as though i t were a2741:

APLPORT UNIT=X'40',TYPE=2741and the 1050 is coded:

APLPORT UNIT=X'30',TYPE=1050Final ly, th e dial-up ports are coded:

APLPORT UNIT=(X'lE',X'23'),TYPE=AMBIGWhenever two unit addresses are given in an APLPORT macro, they areassumed to defi ne the 1 imi ts of a s e que nc e of addresses, a ll ofwhich are to be used w;th APLSV

..


16/97

-13-The APLSV system has now been specified. The macroinstruction INSTALL will produce a deck containing the JCLstatements necessary to ins tal l APLSV and TSIO on APLPAK, create asecondary nucleus in SYSl.NUCLEUS on SYSPAK, and connect the main

system catalog on SYSPAK to the TSIO catalog on APLPAK. However,the JOB card for this deck must be supplied. This can be done withan assembler REPRO statement, as follows:REPRO

//APLINST JOB (ACCOUNT),NAMEINSTALLThe decks to run APLSV, the APLSV Uti l i ty , and TSIO are produced byth e p roduction macro RUN. Each requires a JOB card. The job namesof the APLSV jobs must begin with the characters which werespecif ied in the JOBNAME parameter of th e APL macro. Thus,

REPRO//APLUTIL JOB (ACCOUNT).NAME.TYPRUN=HOLDRUN UTILITYREPRO//APLSV lOB (ACCOUNT).NAME,TYPRUN=HOLDRUN APLREPRO//APLTSIO JOB (ACCOUNT).NAME.TYPRUN=HOLDRUN TSIOEND/* . .produces the decks. An END card terminates the assembly, andbecause the //SYSIN DD DATA statement was used, the END card mustbe followed by a delimiter.

The actual ins tal la t ion is performed by copying thefnstallation macro l ibrary from th e distr ibut ion tape to disk andthen running the assembly j u s t . described. This assembly willproduce four jobs in the SYSPUNCH data set which must be largeenough to c ontain approximately 1,000 card images. The-four jobsshould be separated, and the job APLINST run to produce the APLSVsystem on APLPAK and create a second VSl or VS2 nucleus on SYSPAK.SYSl.NUCLEOS must be large enough to contain a secondary nucleus.Once th e APLINST job has run to completion, the secondarynucleus, IEANUC02, in the SYS1.NUCLEUS data set on SYSPAK must beloaded. In order to do this the operator must set the rate switchon the CPU to instruction before pressing the LOAD button.When the machine stops, he must enter alter/disp)ay mode and al termemory location 8 to hexadecimal F2. He must then set the rateswi t ch back to process, and press s t ar t , I f the s y s t em has beenproperly installed, the remainder of the IPL will be unchanged.


17/97

xx

-14-When the IPL procedure is complete, the APLUTIL job can be run. Ifthis runs to completion, reading the f i r s t fi le on the distr ibut iontape and producing a l i s t ing of th e distribution l ibraries , theOS/VS modification has been successful, and the nucleus can be renamed as follows://RENAME JOB (ACCOUNT),NAMEII EXEC PGM=IEHPROGMI/SYSPRINT DO SYSOUT=AI/A DO RENAME MEMBER=IEANUCOl,NEWNAME=IEANUC03'

RENAME DSNAME=SYS1.NUCLEUS,VOL=2314=SYSPAK,MEMBER=IEANUC02,NEWNAME=IEANUCOIThis will make the system nucleus which supports APLSV th eprimary one, and eliminate the need for th e special IPLprocedureto load an al ternate nucleus.If an existing APL\360 system is being replaced, a full dumptape taken with the APL\360 ut i l i ty should be suppl led to theAPlUTIL job in , place of th e distribution tape. The distributionl ibraries may then be added to the new system with the APLSVut i l i ty operation SELREST.The ins tal la t ion of APlS\' and TSIO is now complete.The APLSV job is used to s tar t the APLSV system. IfTYPRUN=HOLD was specified on th e jo b cards, both APLSV and APLTSIOcan be read in, APLSV can be released, and when the messages

DQCT051 APL HAS 2 SLOTS, 66 BUFFERSDQCROll SM SIZE 32200appear, i nd icat ing tha t APLSV has s tar ted successful ly, TS!O can bereleased. It should soon type

DQCBOOI TSIO 370 NOW ACTIVEThe operator should sign on by typing, a t a terminal to beused with APLSV)314159 (CR)

where th e APL ) character is 'he u pshift of t he ' typewriter kAYadjacent to th e bottom of the return key, and (CR) indicates th ereturn key, which must follow ;111 keyboard entr ies .


18/97

-15-When the APLSV operator" has been successfully signed on, a)LIB 1

command will produce a l is t ing of the workspaces supplied with thesystem and also test the swapping and l ibrary data sets. The APLSVoperator should)LOAD OPFNS

and follow the instructions produced to verify that APLSV isoperating correctly.TSIO can then be checked for proper operation by)LOAD TSIOPS)QUOTA 314159 100 20

and thenFORMAT,

which will in i t ia l ize the TSIO user data set in preparation forenrolling users. The workspaces OPFNS and TSIOPS are explained inmore detai l in the operating sections of this manual.Users may benecessary, )QUOTAworkspace TSIOPS.commands are found

PART I I , and in the

enrolled in APLSV by use of th e )ADD and, ifcommands. and in TSIO by use of th eSpecific instructions for th e use of thesein the section RJlyllgggg ofsection TSIO opera ion, PART I II .


19/97

-IF-L:lilQn frgw APL\3fiOIf the APLSV systeM i s to replace an owing procedure should be followerl:

Us in g the APL\ 3 r-; I) IJt i l i t v, 0U 1P the APL\ 3 f nu s e r 1 i h r n r lest otape . Hate t ha t a f ul l durno, and not an IPCf"Il'fl P , must he US( '1 .,I . Ins t a l l APLSV as descr ibed .3. Us l nz the l \PL\360 dump tapes o b t a i ne d in tbe f i r s t s t e n as l nou tfor the APLSV Ut i l i t y , ppr f O f r1 a 1 opera t ion to conver tthe l i b ra r i e s to APLSV

tIOTE: This o ne r a cl on wil l c lea r the s ta te l nd l ca t o r s 04= ;'11APL\31)(') wor ksnace s I f l oz l ca l : darnf\r>:e is oiscovpre rl in C'lnAPL\3Fn workspace, the nane wil l he wri t ten onSYSPRlt'T and an e t t eno t wil l be mar:le to co r r e c t the rJC:W'n.":P.Fai lure dur ing darnage correc t ion re su l t s in


20/97

-17-

APLSV Specificat ion Macros---,-----------------------

APL

APLL IB

UNIT=VOLesvc=WSSIZE=SLOTS=JOBNAME:=

UNITeyOL=DIRSe

The unit typeand volume serial of the volume to contain theAPLSV and TSIO load module data set ,APLSVS.LOAD.The APLSV type 1 SVC number, between 200 and255, inclusive.The size of the APLSV workspaces. The rlefoultvalue is C4400. This size may be from 20480 to211200 (2314) or 386400 (3330).The number of areas in vir tua l storage reservedfor workspaces. The minimum default is 2.o to 6 which will begin the job namesof APLSV, the APLSV Uti 1 i ty, and TSIO. Thedefault i s 'APL'. 'The direct access device type for the APLSV userl ibrar ies . May be 3330 or 2314.A l i s t of up to 32 volume ser ials of volumes tobe used for user l ibrar ies . NOTE: Librarydevices must a ll be of the same unit type.The number of user directories fQr accountinginformation. A 64400 byte directory willcontain approximately 200 users. Should be aprime number greater than or equal to 2.If the APLllB macro occurs more than once, eachVOL entry adds to the l i s t of volumes.

. ,

APLSWAP UNIT=VOLe

APLPORT' UNIT=

TYPE=

SAD=

---IThe unit typeand volume serial to be used for the APLSV swapdata set . Repeated cal l s 0' APLSWAP add to thel i s t of volume ser ials and unit types. Up toten extents may be s pec l f l ed , but one willnormally suff ice. (See Swap and Library DataSets, above).The multiplexor address for a te rm ina l acces sport. If the multiplexor channel is not channel0, three-digi t hexadecimal addresses must bespecified. Note that APLSV sUPPQrts only onemultiplexor channel. If a l i s t of two addressesis specified (see exai ip l e ins tal la t ion) , i t isassumed to define th e l imits of a sequence ofaddresses, a ll of whicl are to be used by APLSV.The type of port:AMBIG indicates dialup,Hard wired terminals are specified as follows:TS41 - PTTC/EBCD 2741 or 2740-12741 - CorrespondencE 2741 or 1050 - any 1050 systrm.for a 2702, the SAD (ommand to be used. SpecifySADO, SAD1, SAD2, or SAD3. The de f au l tis SADl.The SAD command is not relevant for a 2703 .


21/97

EXPRESS=-18- '

NO or YES, default is NO. If YES, the port w ill Ibe an express port when APLSV is star ted.Expre s 5 po r t s are d is c us sed inth e APLO' operation sectio n of th is manual.1 . . - ----- ,Macros- - -_.._----------------------..,The unit typeand volume ser ia l for the T510 user directory,TSIO.UTABLES, and catalog. The TSIO catalogwill be connected to the main system catalog bythe ! EHPROGM ut in tv . as I NDEX=TS 10 by theinsta l la t ion 1ob.

TSIO Specif icat ion UNIT=I . VOL=L ._General Specif icat ion Macros

(\

SYSRES UNIT::VOL::

TYPE= '

MACBLK=

The unit typeand volume ser ia l on which the data setsSYS1.NUCLEUS resides. The APLSV type 1 SVC willbe l inkedited , into the nucleus IEANUC01 toproduce nucleus IEANUC02.VSxRy, wherex is 1 for VS12 for V52and y is the release number.For example:VSIR1 Release 1.0 or 1.6 of VS1VS1R2 Release 2.0; or 2.6 of VS1VS2R1 Release 1. 0 01 1. 6 ofVS2The BLKSIZE of SYSl MACLIB.

APLGEN UNIT=VOL= The unit and vot urn.:APLSVS.GENI.IBl ns t a l l a t l on ,ser ia to beand A LSVS.PUNCH Llsed for thedata se ts during

I-------------------------------,-----------{The unit typeand volume ser ial ,may be omitted,request for spaceUNIT=VOL=WORK for scratch dEta se ts . VOL=in which a is made.t - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - . , , - - - " ' !TAPE UNIT= The type of tape unit to be usedins tal lat ion. ' f not specified,assumed. for APLSV2400-3 is

Production MacrosINSTALL

RUN

blank Instal l both ! . and TSIO.APL Ins ta l l APLSV on: ..l.T510 Instal l TSIO on 1 APL Produce APLSV ru deck.T510 Produce T510 run -Ieck ,UT III TY Produce Uti l i ty 1n deck.


22/97

/"-'.

iRETENTION AllOCATION SPACE NUMBER OF1I BRARY DSNM1E TYPE 2319 3330 DATA SETS MACROAPlSV user l ibrar ies 0 APLSVS.APllIBX 1 SEE STORAGE REQ 1-32 APlllBAPLSV swap data se t P APLSVS.APLSHAPO 1 1 APLSWAPAPLSV instal lat ion macros G APlSVS.GENlIB 2 3 cylinders 2- cy l i-nders 1 APLGENAPLSV load module l ibrary P APLSVS.LOAD 3 17 cylinders 10 cylinders 1 APLAPLSV object module l ibrary G APLSVS.PUNCH 3 6 cy.linders 4 cylinders 1 APlGEN SIO user table P TSIO.UTABLES 3 2 tracks 1 track 1 TSIOTSIO local catalog P SYSCTlG 3 1 cylinder 1 cylinder 1 TSIO\


23/97

(

-20-PART II

APLSV OPERATION1.!J1J:Q.Q.!J.f!lQ.!J

The responsibi l i t ies of the operator of a system whichIncludes APLSV are somewhat different from those of an operator ofa batch system, primarily because APLSV is interac t ive and usersexpect to communicate with the operator when they have questions.An APLSV sYstem is a ut i l i ty and should be constant and re l labie .The user builds his opinion of the' system on th e basis of I tsre l iabi l i ty and quality of service as exper ienced at the terminal.From the point of view of the host operating system, APLSV isa job which can be s tar ted by a s t ar't command, and which normallyterminates by conventional return. The host system'operator 'sconsole is only for s tar t ing and stopping the system. APLSVi tse 1f is managed by APLSV and Q.l2gr!Qr entered a t a part icular APLSV terminal referred to as th e 19rmlDl. The hf1SY which is used to build and maintainth e APLSV l ib rpr ies , is run as a batch job, normally when the APLSVterminal system is no t running.The APL\360 User's Manual. (IBM Publication GH20-0906), andthe APLSV--User's--Manual--(IBM Publication SH20-1460) containins t ruct ions-for signing-on and off the APLSV and for usingsystem commands. Knowledge of APL by the APLSV Operator is notrequired but is useful , since i t enables the operator to make moreeffective use of the operator functions and to answer userinquiries about system operation direct ly

.!.!:.tlm?; The date and time must be correctly set before APLSV iss tar ted. Changing the date or time set t ings while APLSV is runningwill invalidate APLSV account ing informat ion.The job to run. APLSV punched by. the RUN APL macro duringAPLSV ins tal la t ion can be entered by an OS/VS reader and ini t ia tedby an in i t ia tor , or i t can be cataloged in SYS1.PROCLIB and startedfrom the'OS/VS operator ' s console by a s ta r t command of th e form:s aplsvAPLSV is made up of fourthe APLSV component code, DQC,executable module, followed bymodule:

modules whose names each begin withfollowed by the le t ter E denoting ana le t ter which denntes the kind ofA an APLSV in terpreter moduleS an APLSV supervisor moduleR a shared-variable processor moduleT a supervisor in1t ia l izat ion module

The remaining two characters in each name specify the version to . beused. Normally, the names are DQCEAOO, DQCESOO, DQCEROO and"DQCETOO.


24/97

(

-21-The APLSV region or part i t ion is divided into two areas inaddition to the area where the code resides. The f i r s t area,specified in parentheses af ter the supervisor name, con ta in s buf fe r

areas for terminals and workspace slots . This area must be largeenough to contain at least two workspaces, and six buffers for eachport configured. Each buffer is 32 bytes long. If the size ofthis area is not specified or i f the specified is too small,.the minimum possible sto ra ge w ill be used. The seconn area is usedby the shared variable processor. I t must be at least twice aslarge as the largest value to be passed between sha ring processors ..The message INTERFACE CAPACITY.' EXCEEDED will be rece i ved bv APLusers who attempt to pass values larger than allowerl by thisparameter. If this parameter is not specified, 10K will he used.

If the APLSV in i t ia l ization routine detects an error in theparameter f ield or fa i l s to find a module in the load l ibrary, amessage is printed a t the OS operator 's console and a correction isrequested. The pos sibl e act ions are:1. Cancer the job, by replying 'CANCEL' to the me ss age .2. Ignore the error , by replying rut.3. Correct the error by specifying a replacement module in thesame way i t would be specified in the execu te statement ors t a r t command. To obtain a l is t ing of the modules to be loadedand the storage to be allocated, include,* in th e reply. Allentr ies must be delimited by commas, and storage requestsshould be enclosed in parentheses following the appropriatem od ul e name.

Figure 3 shows a sample error message an d the appropriatecorrection.When in i t ia l izat ioncompleted, the messages and ver if icat ion have successfullyDQCT051 APL HAS yyy SLOTS, nnn BUFFERSDQCROOI SM SIZE zzz

are sent to the OS operator, Indicating the nurnher of APLSVworkspaces (SLOTS) which will reside in the APLSV regionconcurrently, the number of input/output buffers available forterminal operation, and the size of the storage area for sharRdvariables (stD. these messages are printed, APLSV l soperating. Users may not use APLSV ... howeve r , until the APLSVrecording terminal has been signed on as described in the nextsection.


25/97

-22-s aplsv" , (a11,s11)DQCIOOi MODULES NOT FOUNDOQCEAll*00 DQCIOHJ GIVE IFICATI ons OR 11rOO,IAOO,*1DQCI041 ULE SIZEDQCEAOODQCERll 10000DQCESllDQCETll*00 DQCIOni GIVE MODIFICATIONS OR Ur OO,u ,DQCTOSI APL HAS 2 SLOTS, 1023 BUFFERSDQCROOI St1 SIZE 9240

FIGURE 3: SAMPLE STARTUP REPLYIbg EgQrglng Igrmlngl

The terminal signed on with the account number 314159automaticallY becomes the APLSV recording terminal. I t behaveslike any other APLSV terminal, with these exceptions:( 1. I ts keyboard is normally locked.before Input can be entered. Attention must be signalled

2. Messages are logged on I t whenever users sign on or off theAPLSV system. Users can sign on and off only when I ts keyhoardis locked.

3. I t is always System managementfunctions which result in error messages whennon-jir l-vl leged terminals can be executed atte rmi na 1comMands andattempted atthe recording

Output l n te r r u p te d by an attention signal is r e t ransmi t t ed .The recommended reco rd i ng te rmina 1 is an Ion 2741Communications Terminal with th e Int er rup t f ea tu re . Other terminaltypes can be used, but the recording terminal must have a for signalling attention. - - - -The recording terminal may be signed on by typing ) 314159(followed by a colon and pa3swora If one has heen establ ished) .After th e recording terminal has been signed on, there Is a30-second grace period before other users are allowed to sign on,giving the APLSVoperator time to load a workspace. of operatorfunctions, se t express ports If necessary, and establish anappropriate message to he sent to users as they on, using the

)llIPA command as described in Privileged APLSV system commands.


26/97

-23-)HIPA is one of a class of system commands which may be usedonly at a privileged terminal (for example, the recording terminal)and thus are not documented in the user 's Privilegedsystem commands ar e descri bed in a later section of this manual.

Similarly, the system management functions contained in the OPFNSworkspace may be execu ted only a t a privileged terminal.

If APLSV cannot run for some reason detected by the APLSVini t ia l izat ion routine, execution terminates and one of themessages from Appendix A is pr l n ted on the OS operator ' s console.APLSV, once ini t ia ted and running, requires no action fromthe OS operator 's console; communications except thoseassociated with selector channel errors are directed to therecording terminal. APLSV may, in an emergency, be by astop command (for example, p aplsv). Users signed on at the timewill lose their active work, and current accounting informat ionwill not be saved If this is done. .The f oll owing p rocedure , executed at the recording terminal,is recommended for th e normal termination of APLSV:

1. Execute the SHUTDOWNdis t r ibuted workspace12rO.functionOPFNS. which isIf th isis conta i ned inunavai l a b l e ; thetype

2. Use the )PA command to advise users that system operation isabout to terminate.3. After allowing a suitable time for users to clean up thei r workand sign' off, use BOUNCE ALL to force off any remainingsigned-on users. Their active workspaces will be saved inthei r l ibraries under the name 4. When a ll ports but that occupied by the recording terminal aresigned off , sign off the recording terminal. APLSV will thenterminate, using the standard OS return mechanism/; about tenseconds after the accounting in formation has completed typingon the recording terminal. Users who have not signed off orhave not been forced off when this occurs will not be signedoff and will not have their active workspaces saved inCONTINUE.

Messages are sent to the recording terminal when a user signson or off , and when a user enters a )OPR or )OPRN COMmand.Examples:010) 15.35 .23 09/17/72 ADFALKOFF 271828004 15.37.02 09/17/72_LAM017:RWHEN IS THE SYSTEM SHUTTING DOWN? REI062: I 'LL BE DOWN WITH COFFEE IN 5 MINUTES. RHL


27/97

(

-24-The number in the lef t is the number of the accessport f rom which the me s saxe was sent. The port number is f ol l owed,for sign-on by a parenthesis; for sivn-offmessages, by a blank; and f or u se r-gene ra ted hy colon.

An underlined R following the colon in dic ate s th at the sender the )OPR command, and is ewa l t l nz a reply. If no E. f o l lows, thpcommand was )OPRN and no reply is expected.Any message sent to the operator before user has oncauses his keyboard to lock, awaiting a renly. The uspr cannotproceed with his unti l the operator fE'Plies.

NOTE: Users who attempt to sign on while tbe APLSV operator ' skeyboard I s unlocked are not allowed to proceed un t l 1 t;'e carri ii":Pis locked ,

The system commanrls described here are privileo:p.rl, ann may hpused only by a user at a privileged terminal. Chapter? of thp U!D!1Sl1 presents In mo r o dptail the rnf>chFlnics or.using APLSV system commands.)ADD accoun t r number user-name[: lock I uuo t e-iad l us trnen t [Cpll-l IMI t 1Effect: Enroll a new user, create a new puhlic l ibrary, or a pr ev lous l v enrolled user 's name, ac coun t e numb e r l oc!-,workspace quota, or cpu-limit. (See also the )QunTA conm?nrl)Normal response: none.Notes: Account numbers 1 qqq desivnate puhlic

tJuMbers higher than 1000 des l ana t e indivirlual users, an d thei rprivate l ibraries . The may contain frOM 1 tn Jlalphanumeric characters, the f i r s t of which must alohabetic.The f i r s t 3 characters of the user-name are userl. foridentif ication in the )PORTS command anrl in operator functionssuch as USER. The quota-adjustment specifies the l n c r ea se (ordecrease i f neRative) in the number of workspaces a usprnay store, excluding the wo r k space name-d CM'TTNlJP. A ouo t aad] us trnen t of zero does no t cbanze the nuo t a , For a new us e r ,the in i t ia l quota is ze o. An account-number he but not removed. If no new lock is the remains unchanged. The pu-limit Is an or decimal. fract lon that deslp;nntes the numher of secClnrls (rolinrie rl totenths) of CPU time allowed a user for a l ine. If the cpu-limit paraMeter is OMitted, i t Is unchangerlfrom Its previous value. A cpU-limit of zero is tavpn asin f in i ty . The l n l t l a l COli-limit value is inf ini ty. lJser-n'arnpand quota-adjustMent must be given when a public l lhraryeven though they have no ef fec t .


28/97

or user account nUMber trpany accumulAted accounti!"'!'"associ e t ed vii th the

(

-25-Examples:

)ADD 1234 JK'l'UTT LF:: HERB 4add J. K. TUTTLE to the system with passworrl HErR and a quota of hworkspaces.

)ADD 1239 PCBRRRY 2 .6decrease P.C. Berry's workspace quota by 2 ann l imit hiM to r.tenths of a second of CPU time per input l ine .)DELETE account-numberEffect: Remove a public l ibrary

APLSV director ies , includinginformation, and drop worksnacesNormal response: none.ExaMple: )DELETE 1212)HI up to 120 characters of textEffect: Prepare a to be sent to each user as r.P. sip"ns on .Normal Response: NoneExampl e: )HI )LOAD 1 tlEf-IS PRINT 1 FOR SY8TEN CHANGPS.Notes: ' )HI followed by a return any previous PTMessage.)PA up to 120 characters of textEffect: Send a public-address to a ll usersNormal response: none.Example: )PA APL SHUTTING DOWN FOR MAINTENANCE AT 23:55.Notes: A PA message may s po l 1 the appearance of users ' ou t ou t ,


29/97

)QUOTA account-number[cpu-l imit]-26-

[l ibrary-quota] [shared-varfable quota]

The non-privileged commands shown below have character is t icss lig htly d iffere nt from the same commands executed a t a normalAPLSV terminal when executed from the recording terminal:)OFF)CONTINUE

The APLSV recording terminal can be moved from one 2741to another while APLSV is running by simply signing off thef i rs t 2741 and signing on the second. Users will not be ableto sign on or off while the operator is signed uff. APLSVterminates following the operator 's sign off only if theSHUTDOWN operator fu nctio n (or 12IO) has been executed.


30/97

-27-)LIB)SAVE)DROP

A privIleged terminal may execute these commands for' anypublic or private librarYh An attempt to save or drop aworkspace belonging to another user is executed as If the userhimself were saving or dropping the workspace.Example: )DROP 1234 CONTINUE)MSG)MSGN

There is no d l s t l nc t lon between these commandsi, s Ince therecording terminal is ready to receive a reply any time thekeyboard is locked. Messages recording terminal arenever p receded by the character B.)MSG OFF and )NSG ON

resul t in INCORRECT COMMAND when attempted from th e re co rd ingt e rml ne l ,

(Passwords on saved workspaces are inviolate. A privilegeduser can neither override nor learn a workspace password. If auser saves a workspace using a lock and then forgets the 10ck r hisonly recourses are: 1) to drop the workspace; or 2) have an ear l ie rversion, whose key is known, retrieved from an APLSV dump tape bythe APLSV Uti l i ty . Account-number passwords can be changed a t aprivileged terminal by an )ADD command, but cannot be removed .

The workspace 314159 OPFNS (Ope rato r Functions) contains acollection of APL programs which are special ized functions forcontrolling th e running sys tem. They enable the operator to dosuch things as set or remove express time l imits , determine freeport numbers, and forcibly sign off designated users. In additionto th e specialized functions, the APLSV operator has available th efull f ac i l i t i es of APL. The operator functions will often be usedIn combina tion with APL expressions and with each other. Each l ine available for use by users of the APLSV system isreferred to as a QQr1. Each port in the system has a QQr1 which is typed to the user when he signs on and off. Somefunctions in OPFNS workspace take port numbers arguments(for example, BOUNCE 1 4 23 would force users on ports 1, 4, and 23off th e system). Others return port numbers a s results (forexample, SUSPECT 20 returns th e numbers of ports which, thoughsigned-on, have been idle for 20 minutes.) The functions which takeport numbers as can also take as arguments the results offunctions which retu rn port numbers (thus, If SUSPECT 20 returned 429 ,38 as the port numbers of users who have been idle for 20minutes, BOUNCE SUSPECT 20 would force the users on ports 4r 29,and 38 off the system).


31/97

(

-28-Some functions in the operator 's workspace may be used tocombine port numbers (thus BOUNCE (SUSPECT 20) EXCEPT 4 would/. if 429 and 38 were the port numbers of id le use rs, force users on port

numbers 29 and 38 off the system, but would not affect the user onport 4.)The. operator functions all Ignore invalid port numbe r s ,Thus, BOUNCE 99999 would result in the report OKAY but no action.

fQL t i A system with many more enrolled users than portsmay find i t convenient to offer some ports on which an automaticlimIt to the length of a session has been imposed. When a usersigns on such an QQL.t, he rece ives the message .;APL. SV"EXPRESS. After the express t ime-limft has expired, the user isforced off and the active workspace is automatieally saved' as theworkspace CONTINUE In his private l ibrary. A suitable time l Irn l tIs typically 5 to 15 minutes. On express ports the )OFF HOLD and)CON'l'INUE HOLP system commands behave 1 ike )OFF and )CONTINUErespectively.

Ports may be designated as express ports during systeminstal lat ion and while APLSV is running. 'Operator The following sections describe the principalfunctions included in the distribution workspace OPFNS., Thevariable DESCRIBE in OPFNS contain a brief summary of thefunctions, alphabetically. Functions in OPFNS not describedare auxiliary functions which are used only by o ther funct ions .

The fol lowing functions report or al ter system values thatrelate to all ports of the system.NAME and SYNTAX DESCRIPTIONFREE Returns the phone numbers of a l l port s notcurrently signed on . Phone number.s are associatedwith ports by means of the function INITIALIZE.FREE2496600 2496603 2496608SETLIMIT n Sets the express time l imit to n minutes,effect for any YQgygn! sign-oo at anyport .

SETLIMIT 158

to takeexpress

SHOWHI

(teturns the prior l imit)Reports the current HI message to be printed witheach sign-on.SHOWHIOPR: PHILA- APL RUNNING UNATTENDED UN'l'IL 0730EDTWED. AUG. 5 .


32/97

SHOWLIMI1'

SHOWPA

SHU1'DOWN

-29-Returns the current time lim it for express ports,in minutes.

SHOTYLIMIT8Reports the last PA (public address) message

SHOWPA (blank line means no current PAlConditions the system for APLSV shutdownL All portsnot In use a re d is ab led , and no subsequent sign-onwill be accepted. After the operator off atthe recording terminal, APLSV operation SHUTDOWN Is DQ1 a process

SHUTDOWN.APL SYSTEM SHUTDOWN INITIATED

The following functions report or alter the status of portsof the system; vp stands for one or more port numbers .. Some of theexamples given refer to functions which are described butwhose meaning Is obvious.NAME and SYNTAX DESCRIPTION( BOUNCE vp

DEFUSE vp

Forces the users on the designated ports (with theexception of the recording terminal) to be signedoff, a fter saving the active workspaces inCONTINUE.

BOUNCE 2OKAYRemoves the time limit for the current user of eachof the designated express ports .. The time l imitwill be restored when the user signs off .

DEFUSE 18 19 20OKAY

DEPRIVILEGE vp Removes the users at the designated portsexception of the recording terminal)privileged state .DEPRIVILEGE PRIVILEGED

OKAY

{with thef rom the

KBLOCK vp Makes the keyboards of the terminals on thedesignated ports "normally locked", This is thenormal state of the terminal. In thisstate a terminal can receive messages any time thekeyboard Is lockedKBLOCK USER 809380

OKAY


33/97

( KBUNLK vp

LIMIT vp

PORT .vP

PORTS.VP

-30-Makes the keyboards of th e terMinals on thedesignated ports "normally un I oc kod", This is thenormal sta te of a user 's terminal. It is unwise toleave the recording terminal in th is sta te whenothers are using APLSV because sign-on and attempts will be de l aye d until the kcvboa r d islocked.

KBUNLK USER IJKT'OKAYMakes the designated ports express ports.LIMI'l' PHONE 249-6600 2496601 2496602OKAYReports the port numher, phone nUMber, multiplexaddress, user ini t ia lk and account numher for eachof th e designated ports.

PORT ON2 2496601 012 LAM 2673863 2496602 013 XPB 4000000, 22 2496621 026 P4I 123448 2496647 040 FeD 418965128 2496727 098 OPE 314159130 2496729.09A APL 1776Reports in more detail than PORT the status of thedesignated ports. The additional includes the connect-time, CPU-time, and sir.n-ontime of the port.

PRIVILEGE vp

UNLIMIT vp

Places the users at the designated ports in theprivileged sta te . This will remain in effect ,unless revoked via the DEPRIVIEGE function; untilthe user signs off. In general, no one rut theoperator and APLSV system programmers shoulr! everbe privileged.PRIVILEGE 44

OKAYRemoves the express port status of the . ports. (Note the difference between UNIMIT anoDEFUSE. )UNLIMIT PHONE 2496600 2 496 601 2 496 60 2OKAY


34/97

-31-The following functions return a vector of port numbers; vistands for one or more integers.

tlAME and SYNTAX DESeRt

(

11LL

DEFUSED

DOWN

EXPRESS

MPXAD I XX I

OFF

ON

PAWAIT

PHONE vi

PRIVILEGED

Returns th e numhers of all ports in the system inascending order.ALL1 2 345 6 7 8 9

Returns the of the ports that are currentlyexpress but heen rle fuserl hy the DRFUSRfunction.DEFUSED2 3Returns the numbers of th i ports that

DOWN(empty l ine indicates no ports are disahled.)Returns th e numbers of the ports currently inexpress s t a trs ,EXPRES:.;123Returns the number of the port to thehexadecimal multiplexor channel address xx, whichmust be enclosed In quotes.MPXAD I ;' 3 I6Returns the numhers of th e ports not currentlysigned on.OFF3 6 7 9Returns the numbers of the ports signedon.

ON,1 2 4 5 8Returns the numbers of th e signed-on ports thathave not re ceived th e most recent PA message.

PAWAIT2Returns numbers of the ports cor respondin3 tothe designated phone numbers.

PHONE 24966034Returns the numbers of the ports whose users arp.current ly pr iv i leged.

PRn'ILEGED8


35/97

SUSPECT m

USER vi

USER ' abc '

-32-Returns the numhers of the ports on but withno act ivi ty In the las t m minutesSUSPECT 204Returns the numhers of the ports a t which userswith the designated account numhers are on.USER 3001 2604194 0(0 indicates not signed on.)Returns the numhers "6f thA ports at which userswith th e designated in i t ia ls are signed on . (Seealso th e )ADD command.)USER 'JAB'5

The following functions produce groups of port froMgroups of port numhers; vpl and vp2 stand for one or More portnumhers.UAME and SYNTAX OESCRIPTION

(vpl AND vp2 Returns the numhers of the ports that occur in bothvpl and vp2.1 2 3 AND 2 3 42 3

PRIVILEGED AND NOT USER 3141595numhersvpz ,vp2)EXCEPT 3

VPl EXCEPT vp2 Returns th ehut not invpl AND NOT1231 2

of th e ports that occur in vpl(vpl EXCEPT vp2 is the SdmG as

NOT vp2

vpl OR vp2

PRIVILEGED EXCEPT USER 3141595Returns th e numbers of th e ports that do not occurIn vp2, in ascending order. (NOT vp2 is the sameas ALL EXCEPT vp2NOT ON367 9Returns th e numhers of the ports that occur inei ther vpl or vp2, in a scend l ng o rde r ,1 2 3 0,7 2 3 4123 4


36/97

-33- APLSV multiprogramming is meterc0 hy aunit of time called a The quantum is the maximum timewhich can pass before a scheduling decision is marle.

When operating in a multiprogramming environment, APLSVensures tha t other part i t ions r eceive f requen t CPU service byalternating i ts own prior i ty between high anrl low. Uhen APLSV haslow prior i ty , other part i t ions will get CPU service if they are notquiescent.The nominal proportion of time that APLSV has priori tyis controlled by two system parameters, preset in th e distrihutee!system to 50 percent but modifiahle a t any time hy the use of thpPRIORITY function. Unless APLSV and some other part i t ion bo t hrequire heavY CPU service, the p r io r it y s ett in3 will have l i t t le orno ef fec t on system behavior. '

NAME and SYNTAX DESCRIPTION

c

PRIORITY a,b

QUANTUM x

Sets and reports th e proportion of APLSVhigh-priority time. a is the proportion when noports are in use, and b is the proportion when allports are in use. The prior i ty proportion variesapproximately l inearly with the number of ports inuse. a and h are fractions, between 0 an0 1. Ifonly one value is given, a and h are taken to heequa 1 If APLSV is to he run hy i t s e l f , systemoverhead may he lowererl by PRIORITY to 1.PRIORI1'Y 1EMPTY WAS 0 .5 IS 0 .99LOADED f,lAS 0.5 IS 0 .99The APLSV quantum


37/97

-34-Shared Variable Processor Q12gr.!QI E1!!Js.!lQ!J2 lhe which controls the flnw nf inforMationbetween APLSV te rm inal u se rs and auxillary processnrs, such as T510or .hetvJeen two terminals that are vla variahles. SVP runs without r equi ri ne act ion frnm the operator the following f unctions w ill he of most use to system SVMAP prints various s ta t i s t ic s ahout the currnt s t a t e o f SVPoperat on.

(

SVMAPSTARTED OF'FERS WFS GCOL pSVS Tl?ANSFPRRF.D07 .21 .45 102 O o ?9000 100:?5G

NOW +/ON 1tpPS r/+/ON r /1 tpPS RPQUF.8T822.43 .30 3 2 '13 22 1029PROCESSOR VARS PROCESSOR VARS PROCF:SSOR -VARS370 1 399 O 267386 2

STARTED is the time the APLSV systerl VJaS initi


38/97

-35- 819 tyufllQD2 The functions he10w are intended fordebugging the system, not for general use during APLSV operatlon.Improper use of the REP functlon can cause system

'xxx' stands for a hexadecimal quantity of 1 toenclosed in quotes. Hexadecimal arlthmetic is perfor!'11ed2'5 complemente Integers without quotes may a1so hethese functions, and are interpreted as decimal va1ues.8 rligits"In 32-bi tused with

NAfvlE and SYNTAX, xxx' AH 'xxx 1

ASUP

DESCRIPTIONReturns, in hexadecimal, the sum of the twova1ues.

'3A ' AH 2OOOOOOSCReturns, rn rlecima1, the heginnlng arlrlress ofthe APLSV supervisor.

ASUP458362

ASUREL 'xxx' Ca1culates the absolute arlrlress ofoffset 'xxx' from the heginning ofsupervisor.DISPLAY ASUREL '140'0000009D

rc1atlvcthe J\PLSV

DISPLAY 'xxx' Returns, Infour bytes a tDISPLAY00006298

the contents of theth e es igna tcd storage adress.16

'xxx' DISPLV 'xxx' Disrlays, in hexadecimal, the contents of th0.str ing of bytes whose length is given by thclef t operanrl, star t ing at the main address glven hy the operando12 DISPLV ASUP

06FF88 900FEC58 47FOE1EC 9500EAE5DTH n

HTD 'xxx '.

Returns the hexadecimal quantity equivalent ofthe integer n.DTlI 12

OOOOOOOCReturns the decimal integer equlva1ent of. thehexadecimal quantity.

HTD '9C'156


39/97

'x.xx' REP 'xxx'

SVCLEAR id

, xxx' SR 'xxx' ,

-36-Replaces the four hytes of main designated by the le f t operand wlth the rlghtoperando The functlon f l r s t l l s t s the nroposeclchange ano waits for a rcply. Typing anythingexcept a perlod followed by a carriagc returncauses the patch to be skipped.(ASUREL ' 1 40 ' ) REP '0000009C'0700C8 0000009D + 0000009C ?(enterlng a period permits replacement)0700C8 0000009D+0000009CClears the Shared Varlahle Processor table entryfor auxillary id. Thisfunctlnn Is supplied tn allow writers ofauxillary p roce sso rs to clecr the ir processorsf rom SVP in an ,f;me rgerlcy. I t villl neve r rE'required In normal operation of APLSV .SVCLEAR 399OFOC20 00016D70 80000000 00003A6A . .399 CLEARReturns, In hexadec imal , t he difference betweenthe two quant i t ies .

'AO' SR 10 '00000096

(XXX' VERIFY 'xxx' Verifles that the four hytes of maln desis;nated hy the le f t arr;umcnt cantain theright If the verificat ion fa l l s , areturn to inmediate execution Is forcerl.Most useful in v/rltlng patchlnr; functions.(ASUP AH ' 1 40 ' ) VERIFY 'ooooooro'

NOT VERIFlrD: 0700CS

Usually, a user1s only contact wlth the orerat lon lsthrough h.is remote terminal. D:Jrinp; a reriod of systerlmalfunction, or when schedule changes have heen too ahrupt ly,or when APLSV does not hehave as expec te ri, the terrlinal can seCMvery remote lndeed. The following suggest lons a re i ntender l a s aguide to runnlng a reasonable APLSV servlce.1. Publlclze an Operator numher for a telcphone ne1rthe recordlng terminal.2. Puhllcize and encourage th e use of the 1 NRWS. l tcontalns functlons for rllsplaying notes to schedules, and schedule dcvlat ions. It a1so contains functlnnsfor the APLSV Operator 's or system prOp,r


40/97

-37-Modifications are in 1 NE/-lS under the name NEflS11/t]UllC.Instructions for th e user are in the APL\3GO User1s t 'anual,Appendix S, ano in 1 NEWS under the name DESCRIBE. Theworkspace 1 NEWS should contain adequate nforMatlon the auxil iary processors availahle at th e central lns tal lat lonfor use with the shared variahle fac i l i ty .

3. Make use of the )BI command to post last-mlnute notes andschedule chanees (and admonitions to look at 1 NEWS.) If APLSVis 1eft running wlth no one at the recorrling terminal, leave a)HI message saying APL IS RUNNING UNATTFNDEn UNTIL 2400, orsome such. To post a Message at the time you sign nn, use)HIPA so that users sienlng on a t the same tiMe you do willa1so get the message.

4. Fo1lowing a system fa i lu re ; bring up APLSV as rapirlly aspossib1e. Rememhcr that auxi11ary processors must be stoppecand res tarted if APLSV fai1s.5.6.

Avoid arhi t rary schedule changes.may Inconvenience many users.A baff1ed user wil1 sometimesoperator via an )OPR mcssage. Tryhim in touch w lth an or atthe questlon, without Jndue rielay.

Rememher that such a chanf,crequcs tasss tance fron theto h is que sti on , putleas t acknowledge rcceipt of

( 7. Use the )PAcommand s ',1ringly. It can nterfere \'Iith a uscr 'scarefully-arranged output. Also, hecause there may he asignIficant delay hetween your sendlng l )PA and the receiving i t , Indicate a l l tiMes by clock time - - for in stan ce,say SYSTEM SllUTTING DOWN AT 21: 30 , not SYSTE/, SJ!UTTIllG DDY/N nI5 MINUTES.

8. No more than five minutes hefore APLSV is scherlulcd to shutdown, execute SBUTDOWN and notlfy users vla a )PA command.Before sIgning off at t he recorr li ng terminal, execute 80UNCE onto f orc ib1y sign off any remaining users. If they are nnt sosigned off , thelr active workspaces anrl thei r CPll- andconnect -t ime charges for that session will he 10st .9. Encourage users to change their account-number passworrlsoccasional1y. Always nclude a passworrl whcn you )ADD a newuser to the system ( let t ing him know what I t 15, of course.)If an enrolled user gets th e response NUMBPR nOT IN SYSTEM \'Ihenhe t r ies to sign on, i t is 1 t h a t h e has inarlvertentlychanged his account-numher password. Two easy ways he coulrlhave done this are by signing off via )OFF: orv i a )OFF:HOLDThe f I r s t removes his password a1together; the i t to the word HOLD. lf neither of these explanations f i t s , or

1f a user has simply fo rg ott en h is password, yo.u can execute an)ADD to change his password to an agreer!-upon \'lord. t1ot0. thatthere is no similar method to recover l passvwrrl-protp.cterlworkspace.


41/97

-38-10. Many important aspects of user securi ty are at thc APLSVnpe ra tor 's d i sc ret ion . The operator has tho ahll i ty mentinnpaboYe to chanr;e account-number pass\'lOrds; to lny otherf"lort priviler;ed to ascertain (via the APLSV Util i ty) thc n.Jr10.Sof a ll \"lorkspaces . in a 1 ir.rary an thc ar:ount of epI! tlndconnect tiMe charged to a user. It is vital fnr userconfidence and for accep tance o f a tiMe-sharing SystcM that

such fac i l i t ies he use with care and discrct ion. For example:a. I'lequire posltive Identlflcatlon (a phone ca l l , nr


42/97

(

.....-39-

PART JI ITSIO OPERAT10N

TSIO Is an auxlllary processor supplied with the APLSV systemwhlch gives users at APL termlnals access to OS/VS data sets . I tIs s ta rt ed a fte r the APLSV terminal system Is . s tar ted, in aseparate region from APLSV, ando uses the shared variable processorfor all communlcation with APLSV users. Detalls on the use of TSIOmay be found In iBM publicatlon, IIT510 Pragram Reference Manual"(SH20-1463 ).TSIO should always be run at a hlgher prlorlty than APLSV. InVS2, this Is accompllshed automatically by the DPRTY parameter Inthe EXEC'card produced durlng, ins tal lat ion. In VSl, however, th eoperator must in i t ia l lze the par t l t ions to be usad for AfLSV andTSIO wlth the VSl DEFINE command so that t heTSIO par ti tio n is

higher in priority than the APLSV pa rt it ion (par ti ti on 1 is higherin prior i ty than par t i t lon 2). The APLSV par t i t ion should bedefined as non-deactivatable, but th e -TS10 par t i t ion, If desired,may be deactivatable. For example, in response to*06 ENTER DEFINITION,.the repl y

r 06,pO=(stp,128k,sn),pl=(g,128k,sa),p2=(g,384k,sn),p3=(ab,384k,sa,last),endwould in l t la l ize a VSl system as follows:PO SYSTEM TASKSPI TSIO PARTITIONP2 APL PARTITIONP3 BATCH PARTITION

128K NOT ELIGIBLE FOR DEACTIVATION128K ELlGIBLE384K NOT ELIGIBLE384K ELIGIBLE

When definlt lon ends, the commandss aplsv.p2s aplts io .pl

wl11 s ta r t theAPLSV system and the TSIO processor in thei r correctpar t l t ions.Note: Acomplete des cr ip ti on o f message IEE802A is contained inIBM Publication GC38-1001 "05/VS Message Library: VSl SystemMessages ll , provldlng more information on the DEFINE command.


43/97

-40-

TSIO normally ooes not require intervention from the operatorunless an APLSV user requests access to a date or passwordprotected data se t , or requests use of a tape or unit recorddevice. These requests, which take the form of operator messages- on the OS/VS console, should not occur unexpectedly. If they do,the OS/VS operator should reply.

r xx , 'M'to deny thepermissiondevice, thein th e TSIO

reques ts . If , however, the APLSVto update the data se t or use theaperator should rep1y fo110wing themessages portion of sectipn.user has obtainedtape or unit recordinstruetions given

The operator can use the OS/VS modify command with TSIO. Themodify command has th e formf procedure-name.identifier,subcommand ,

where procedure-name.identifier 1s the argument given to th e OS/VSs t a r t cOmmand to ini t ia te TSIO (for examp1e, ap1ts io . ts io for VS2(ap1tsio.pl for VS1) and subcommand is one of the fo11owing TSIOsubcommands, which cause the action given.

.( USERSSUPPRESSSHUTDOWN

ALLOW

DETACH

Lists the APLSV sign-on identificat ion of eachcurrent TSIO user, and the unit address of thedevice he is using, i f any.Prevents further users from signing on to TSIO.Prevents further users from signing on to TSIO,and conditions TSIO so that, when a11 currentusers have signed off , the TSIO program wi11terminate.Returns TSIO to normal from SHUTDOWN or SUPPRESSs tate .Forces a11 tape or unit record devices off ofTSIO. Usefu1 only in certain emergencies, suchas when an APLSV user has requested a specif icstandard labe1 tape, and the tape he hassupplied has an incorrect 1abel.

The stop command,. p procedure-name.identifier, can be used toabnorma11y terminate TSIO with a dump. TSIO is an OS/VS subsystem,and the OS/VS cancel command may not be used against i t .


44/97

e

-41-Examples:s aplts io .plDQCBOOI TSIO 370 NOW ACTIVEf aplts io .pl ,users .DQCB071 TSIO USER DEVICE267386 3601234 oac267386 182f apltsio.pl,shutdownf apl ts io.pl ,usersDQCB061 TSIO SHUTOOWN IN OQCB071 TSIO USER OEVICE1234 OOCNOTE: When TSIO Is started from a batch stream InVS1, the modifyand stop commands must specify the JOBNAME only.

The maximum number of users that can use TSIO concurrently Isdetermlned by the region or part l t lon size and the number of DOstatements In the TSIO procedure with DDNAME beginning with WKDD.The WKDO statements Impose an upper bound, and users in excess ofthls number must wait until some other user retracts hisshared-varlable interface. (f suff icient WKOD s ta tements a reavailable, but there 15 insufflclent available space in the TSIOregion or part i t ion for an additional user 's 1/0 buffer s, the userwill recelve TSIO return code 14, indicating TSIO buffers fulloThe TSIO run deck produced durlng APLSV insta l la t ion providestwenty WKDD statements.Ihe IS1Q QQgrlQr TSIOPS.

The use of TSIO is con tr ol le d by functlons in theAPLSV dlstributlon workspace TSIOPS. These func t ionsmst beexecuted a t the APLSV recording Each APLSV user who wishes to use TSIO must be1) Enrolled In the APLSV system by the)ADD command.2) Glven a shared varIable quota ( that is , allowed. to usethe shared variable faci l i ty) by means of a QUOTAcommand.3) Enrolled in TSIO by means of the TSIO operator function,ADD.For example, the followlng sequence of commands, entered atthe APLSV recording terminal, would be necessary to add user 8003to the APLSV terminal system and allow him aCCeSs to TSIO.)LOAD TSIOPSSAVED 2 3 .2 4 ;1 5 .6 /2 7 /7 3)ADD 8003 RWALLEN:A20 3)QUOTA 8003 .3 3

8003 3 3 .0 o RWALLENADD 8003


45/97

-42-There are 5 functions in the TSIOPS workspace.ADD n,d

DELETE n

Adds user n to TS10 wlth user level d orhls user level. (See the descrlptionlevel discrimlnants below.) If dspecif led, zero 15 assumed.Removes user n from TS!ODELETE 8003 8004-8003 O8004 14

changesof user15 not

800280109005314159(

DISPLAY n

ULIST

FORMAT

Dlsplays the user level of user n, if n has beenadded prevlously.DISPLAY 8002 90018002 14Produces, as an explic l t resul t , an array,containing in i t s f i r s t column th e sign-onidentlficat lon of all users enrolled in TSIO andin I ts second column the level assoclated witheach user.

ULIST14O1015

See "In i t ia l izat lon of TSIO", below.

TSIO users are normally a llowed to create data sets only onthe specific direct access volumes whose volume ser ia ls arecontained in the TSIOuser volume l i s t , which is maintained by th efunctions in TS10PS as follows.ADJ) 'vol ser '

DELETE 'volser '

DISPLAY PVOLS

Adds a volume ser ial to the user volume l i s t ,which 15 Ini t la l ly empty.ADD 'APLPAK'Removes a volume ser ial from the listo Returnsthose remalning.DELETE 'APL222'APL111APLPAKReturns the current user volume l i s t as anarray.

DISPLAY PVOLSAPLll1APLPAK


46/97

-43-

Access to data sets in the host system from. APL5V terminalsis res tr ic ted by means of discrimlnants which may be supplied tothe T510PS function ADD. The dlscrlminants, and their effect .onthe behavior of T510 towards the user to whom they are applied, arBas fol1ows. More detal ls may be founo In the T510 user 's manual.DISCRIMINANT eODE EFFECTSPACE 8 present: The T510 user cau directaccess space on any TS IO vo 1ume, i f hedoes not have UNIT level authorizatlonand on any OS/V5 vo 1ume, i f he does.

absent The'TSIO user cannot allocate space. A5YSTEM user (such as theoperator) must al locate any data setshe is to write. If he has th e ACCESSdiscriminant, however, he can read andpossibly update, but not rewrite (withSW), data sets created by other,non-SYSTEM level, users.

UNIT

ACCESS 2

present: The TSIO' user can use th e TSIO commandparameters UNIT and VOL . to access anydirect access device, and, with theoperator1s intervention, any unltsupported by BSAM on the system.absent: The T510 user Is restr ic ted to thedlrect access volumes in the TSIO user

volume l istopresent: The T510 user can read (using the T510command SR) other T510 users ' . datasets , if. he knows t he ir i dent if ic a ti on .He can use the T510 commands IRand IRW aga inst other L1ser' s data sets,

i f they are sui tably formatted.absent: The T510 user cannot access any datasets but his own.

SYSTEM 1 present: The T510 user can accessin the OS/V5 system byse t name. He may alsocertain restr icted TSIOparameters.

any data setexp1icit datamake use ofcommands and


47/97

-44-absent: The TSIO user may not access systemdata sets since all data se t names areprefixed with TSIO followed by anencoding of his APLSV signonidentificat lon, or, i f he has ACCESSpermlssion, the signon identificat ionof the owner of th e data seto

level is encoJed for a given user by adding together thenumeric code for ea eh discriminant and suppling this sum to th e ADDfunetion. For example,ADD 8003 10would add user 8003 to TSIO with the discrlminants SPACE andACCfSS, which are codes 8 and 2 respectlvely. Qf

When the APLSV system is f i r s t instal led, the followingsequence must be ente red at the operator 's to lni t ial izeTSIO so that the TSIOPS ADD functlon can be used:

Center a perlod)The typing element will nod when the operatlon is complete.(

)LOAD XSIOPSSAVED 23.24 .25 6/07/74)QUOTA 314159 100 10314159 10010 .0 5 OPERATORFORMATWARNING. TSIO.UTABLES BEING CREATED. ENTER TO CONTINUF.

FORMAT formats the TSIO.UTABLES data seto


48/97

(

-45-

if 1510 encounters a system error whJle performing someoperation on the behalf of an APLSV user, the user wlll receive ntwo-element return code: 30 x, where x is one of the integers 1through 8. (See SH20-1463, T510' Program Reference Manual). Thesevalues of x have the following meanings:x Meaning1 VTOC FULL - The volume table of contents of th e volume on whichTSIO attempted to allocate a data set cannot contain anyfurther DSCSs.2 Allocation falled - OS/VS DASO space allocation failed hecauseof an OS/VS error .3 DO Card missing There' is an error in the WKDD DD cardsequence in the TSIO p rocedu re or run deck.4 System Queue Error - OS/VS experienced an unrecoverable l/O

error while accessing SYSl.JOBQE.5 System Queue Full - There were no free records on SYSl.JOBQEwhen requlred.6 Directory Error - During the close of a member of a partitionerldata se t , STOW fai led , e ith er because the is ful1 orbecause of an l/O error .7 CATALOG fal led - The OS/VS CATALOG operation failed duringaCLOSE, RENAME, or explic i t CATALOG. This can be caused by aninconsistent catalog structure or by an l/O error.8 OPEN fai led - An attempted OPEN was unsuccessful. This returncode wi1l be received if the OS/VS operator repl ies 'mI to arequest to update a date-protected data set or uses the detachsubcommand in a TSIO modify command.In most cases, a system error return code will be correlatedwith a OS/VS message on the system operatorls console; and theaction, i f any, associated with that message should be taken.


49/97

(

-46-PART IV.

APLSV UTILITY OPERATION

The APLSV Util i ty program provides maintenance for th e APLSVLibrary such as formatting disk packs, copying workspaces from diskto tape and vice versa, verifying disk ano tape reaoanil i ty , anoprlnting and punching accounting iQformation. Through the use ofthese Uti l i ty operations, an ins tal )at ion can, for instance,1. Provide tape o( disk backup copies of APLSV l ibrary dlsks.2. Ret ri eve ind iv idua l workspaces or l ibrar les from backup copies.3. Reallocate the APLSV Librarles to conform to changed extent

boundaries.4. Write selecteo workspaces onto tape for transmission to anotherAPL insta11ation.5. Bill users for APLSV service, using ins tal lat ion accountingroutines.

8f1 !Qg or !Qg fllg refers to the one or more reels nftape written by a Util i ty operation. 11hrry refers to an ins ta l la t ion ' s whnle col lec t ion ofdirector ies and workspaces, as stored on disk. 11hrry orygr llbrry refers to the col lec t ion of workspaces associated witha part icular account number. refers to a card or a card lmage, depending on devicetype .Directorias holo informatlon concerning th e enrolled users, accounting records,passwords, and 11sts . ofsaved workspaces. or refers to the portion of adisk pack described in a VTOC as being allocated for APLSV Library

storage. Library extents are numbered, beg inning with O, in theorder in which the volume ser ial numbers are identif ied in the ins tal la t ion macro cal1s.

frd refers to a card containing al ibrary number and, optionally, a workspace name. WorkspacAselection cards designate part icular l ibrar ies or workspaces forlJt i l i ty operations.A.-maximum of 100 workspace se lcc t ion cards maybe included in a runo refers to the l ibrary number, ano name, of a workspace.

k A i5 any operation that writeswor spaces to ulsk or tape.


50/97

-47-

TableOperation. 1, immediate1y below, summarizes the APLSV A detai1ed description of each operation fol1ows.Opera tion Para- Optiona1 Run Disk or Purpose andName meter Listing wi th APLSV Tape l/O RemarksACCTG O none ves disk Lists users and,1 optional1y,workspace names

2,x none ye"s disk Users and workspacenames for directory x-- 3 none ves disk Users and workspacenames for saved since 1ast fu 11DUMP

BILLING none none no disk Produces b i1 1 i nginformation usinginsta11ation-rlefinedforma t t i ng routinesCREATE O ws names no both A11 ows changingwritten number of directorieson disk wi thout forma t t i ng( l ibrary data sets

1 ws names no both Spec ia 1- purposewritten fonn of RESTOREon disk for sysgen

DISKFMT 1 i brary none no disk Hrites ful1-trackextent records on a l ibrarynumber extentDUMP tape ws names no both Wr i tes al 1 director-record written ies and workspaceslength on tape (wss) to tapeINCDUMP tape ws names no both Wr i tes al 1 director-record written ies and recent1y-length on tape saved wss to tapeLEVEL O none ves none APL\360 compatibi1ity

1 none ves none APLSV compatihi1 i ty.RESET none none no disk Reset time accounting.---RESTaRE none ws names no both i tes di-ectorieswritten and workspaces fromon disk tape to 1ibrary disk


51/97

HETRIEVE

SELDUMP

SELREST

TESTB1LLTVERIFY

none

taperecordlengthnone

none

none

ws nameswri t tenon diskws nameswrit tenon tapews nameswrit tenon disknonews nameson tape

no

yes

no

yes

yes

both

both

both

disktape

Searches dump tapefor selected wss andadds them to l ibrary\A1rites selectedworkspaces to tapeAdds al1 worksDaceson tape to l ibraryLlke BILLING, but noaccountin; resetReadback check ofclump tape

VER1FY l ibrary noneextentnumber"

yes disk ver if fes the reada-bi l i ty of a l ibrarydata setNSLISTWSDUMP

none

none

none

ws con-tents onprintet '

yes

nononedisk

Makes other ODera-t ions l i s t ws namesPrlnts contents ofdamaged workspace onSYSL1ST In hexarlecimal

TABLE 1: APLSV UTILITY OPERATIONS


52/97

-49-Uti l i ty operatJons are specified by free-field control containing an operation name and, in some cases, a numerlcparameter. Parameters may not be omitted. The operation name parameter, if . any, must be separated by at least one blank. \

completely blank card is gnored., Any number of operations may bperformed in a single Uti l i ty runoThe parameter for operations that wrlte tape designates themaximum tape record length . The upper l,imit is 32750; the 10WHl imit i s t h e greater of 500 and the workspace size dlvided by 190.A workspaceselect ion .'card contains a l ibrary numbct'optional1y followed by one or more blanks and a workspace name.The absence of a name designates the entl re l ibrary.Workspace passwords must not be presento In workspace names, A --and 0-9 are represented by standard EBCDJC codes, 4-Z arerepresented by lowercase EBCDIC alphabetics , and 6 and Q arerepresented by EBCDIC - an

APLSV Operations Guide IBM SH20-1461-0

Documents

Transcript of APLSV Operations Guide IBM SH20-1461-0