Fujitsu BS2000 V10 operating system User Commands

Command description

The ABEND forces the current job to abort. A user memory dump (memory classes 5 and 6) is output if

OPTION DUMP=YES has been specified previously, or if the DUMP prompt was answered with YES (OPTION DUMP=STD).

For the purposes of the dump, a disk file is initialized with the name

"$userid.DUMP.jname.tsn.ser" (where tsn = TSN of the terminated job, ser = serial number).

Otherwise, ABEND functions in the same manner as the LOGOFF command: the memory pages and devices assigned to the task are released and the system asks whether system (output) files are to be output to printer or tape.

The system files SYSLST and SYSOUT are not printed out if they are empty when the

ABEND command begins to execute.

If an ABEND command is specified while a program is loaded, any ABEND-STXIT routine that has been defined is activated unless the ABEND command is called via the

CMD macro (see the "Executive Macros" manual [5]).

Any monitoring job variable for the job to be terminated is set to "$A".

U3586-J-Z125-7-7600

ABEND

Format and operand description

Operation

ABEND

Operands

[BUT][,TAPE]

[TAPE][,BUT]

[NOSPOOL][,BUT]

[BUT][,NOSPOOL]

BUT

TAPE

NOSPOOL

Only works in interactive mode. You enter it to indicate that you wish to start a new job after terminating the current one, and that therefore the terminal should not be disconnected from the host. If

BUT is omitted, the terminal will be diconnected from the host.

Causes the system files to be output to tape rather than to printer.

The files SYSLST/SYSOUT are written to the same tape in a file with the name "TAPE.TSNnnnn", where "nnnn" is the TSN of the job being terminated by the ABEND command.

The SYSOPT file is written to a separate tape and is likewise given the file name "TAPE.TSNnnnn", where "nnnn" is a new TSN. You are informed of this via the SYSOUT file.

TAPE is only supported for reasons of compatibility. The

PRINT or PUNCH command is used to spool out system files to tape.

Suppresses output of system files SYSLST and SYSOUT to printer.

U3586-J-Z125-7-7600

ABORT

ABORT Abort procedure

Command description

The ABORT command enables the user to interrupt a procedure. Procedure mode is terminated at the point where the ABORT command is issued and SYSCMD returns to primary command input (cf. the ENDP command: "Return to the preceding procedure level", see also example 2). All the system files (including TASKLIB) which were opened during procedure execution are closed and their primary allocations are restored.

Format and operand description

Operation

ABORT

Operands

The ABORT command is specified without operands.

U3586-J-Z125-7-7600

ABORT

Examples

Example 1

Fig. ABORT-1 ABORT and ENDP commands at procedure level 1

The arrows indicate the path of SYSCMD and SYSDTA. At procedure level 1, the

ABORT command is identical to the ENDP command.

U3586-J-Z125-7-7600

ABORT

Example 2

Fig. ABORT-1 ABORT and ENDP commands at procedure level 3

The arrows indicate the path of SYSCMD and SYSDTA. The ABORT command results in a branch to the primary command input; an ENDP command at this point would return to procedure level 2.

U3586-J-Z125-7-7600

ADD-ISAM-POOL-LINK

ADD-ISAM-POOL-LINK Define ISAM pool link name

Transaction mode (DCAM) (page 33)

Command description

The ADD-ISAM-POOL-LINK command allows a task-specific pool link name to be assigned to an ISAM pool. The pool link name is entered in the table of pools.

Unequivocal identification of an ISAM pool is possible only by means of its name, catalog ID (host system) and its scope.

When a file is opened, a check is carried out as to whether a pool link name has been specified for it and whether an ISAM pool exists for that link name. The pool link name is entered both in a table and in the TFT. Entry in the TFT is by means of the FILE command.

Format and operand

Operation Operands

ADD-ISAM-POOLLINK-NAME=name

LINK

,POOL-NAME=name([CAT-ID=

*DEFAULT-PVS catid

TASK

][,SCOPE=

HOST-SYSTEM

])

LINK-NAME

=name

POOL-NAME

=name(....)

Link name by means of which the ISAM pool can be accessed.

Pool link name. Length: 1-8 alphanumeric characters. The first character must be a letter or one of the characters "$", "#", "@".

Name of the ISAM pool to which the link name is to be assigned.

Pool name.

CAT-ID Catalog ID of the pubset to which the ISAM pool is to be assigned.

=*DEFAULT-PVS

The catalog ID assigned to the user ID is used; default value

=catid

SCOPE

Catalog ID of the pubset.

Scope of the ISAM pool.

=TASK The ISAM-Pool can be used by the user-own task only; default value.

=HOST-SYSTEM

The ISAM pool is available to all tasks.

U3586-J-Z125-7-7600

APPLICATION

APPLICATION Enter DCAM application in CLT

Application group:

Command description

The APPLICATION command is intended for DCAM users; it permits information relating to a DCAM application to be stored in or deleted from a task-specific table known as the Communication Link Table (CLT).

The DCAM application is opened by a DCAM user program; the values in this table replace the corresponding entries in the application control block ACB (Assembler) or in the application structure (COBOL). The link between the CLT entry and this program area is established by means of the link name, which must be specified both in the command and in the program. (See also "DCAM Program Interfaces" [6] and "DCAM

Macros" [17].)

The APPLICATION command can only influence the opening of the DCAM application if a link name has been defined in the program.

Format and operanden description

Operation

APPLICATION

APPL

Operands

[application-name]

,LINK=linkname

[,DISNAME=distribution-name]

[,USEPASS=password1]

[,USEPW=password2]

[,LOGPASS=password3]

U3586-J-Z125-7-7600

APPLICATION

application-name

Specifies the name of the DCAM application. It must not exceed 8 bytes in length and must consist of EBCDIC characters. The first character must be a letter or the character "@" or "#".

LINK=linkname

Specifies a link name of no more than 8 EBCDIC characters, the first of which must be a letter or the character "@" or "#".

This link name establishes the relation between the entry in a process-specific table (CLT) and an area in the program (ACB or application structure).

Special function: If LINK is the only operand in the APPLICATION command, the CLT entry associated with this link name will be deleted.

DISNAME=distribution-name

Specifies the distribution name under which this process is to receive messages. The name must not exceed 8 bytes in length and must consist of EBCDIC characters. The first character must come from the set (A, B, ..., Z, @, #).

USEPASS=password1

Specifies the password which is defined in the primary process on opening a DCAM application and is required for linking a secondary task to a DCAM application.

The password is 4 bytes in length and is either a character constant

(C’xxxx’) or a hexadecimal constant (X’xxxxxxxx’).

USEPW=password2

Specifies the password which must be defined in the secondary process so that it can be linked to a DCAM application. The password is 4 bytes in length and is either a character constant

(C’xxxx’) or a hexadecimal constant (X’xxxxxxxx’).

LOGPASS=password3

Specifies the password which is defined in the primary process on opening a DCAM application and which must be given by the communication partners when establishing a connection. The password is 4 bytes in length and is either a character constant

(C’xxxx’) or a hexadecimal constant (X’xxxxxxxx’).

U3586-J-Z125-7-7600

APPLICATION

Example

When a DCAM application is opened, the APPLICATION command shown below causes the application name to be changed and one of the passwords, i.e. XYZ, to be defined.

Fig. APPL-1 Entering the DCAM application in the CLT

U3586-J-Z125-7-7600

AUDIT

AUDIT Log branch instruction addresses

Command description

The AUDIT command allows you to monitor a program run. This means that you can trace the execution of a program retrospectively by using AUDIT to list the addresses of successful branch instructions. The branch instruction addresses are entered into a special table called the AUDIT table. This table contains 64-word entries and, unless arranged otherwise, is cyclically overwritten.

The AUDIT command can be specified for the entire task run or for a process within that task (e.g. contingency process).

This is also possible after the LOAD command.

The AUDIT table is output by means of the the DISPLAY, DUMP or GET operand or by means of the AID command (see also the "AID" manual [23]).

Application of the AUDIT function to systems with IN-HSI (industry standard normal mode hardware/software interface) significantly increases the program runtime.

Format and operand description

Operation

AUDIT

Operands

[ACTION= OFF ]

DISC

FUNCT

[,SCOPE=

TASK

]

TID=tid

TSN=tsn

]

[,SAVE=n]

[,DISPLAY=YES]

[,DUMP=YES]

[,GET=YES,TABLE=X’addr’]

U3586-J-Z125-7-7600

AUDIT

ACTION

=ON

=OFF

=DISC

DISPLAY=YES

DUMP=YES

GET=YES

SAVE

Activates or deactivates the logging of branch instruction addresses.

Activates logging. If no AUDIT table exists, a new one is created and initialized by overwriting all fields with binary zeros. The current pointer is set to the beginning of the table, and logging is activated; this is the default value.

If an AUDIT table already exists, the current pointer is set to the next field to be written, and logging is continued from that point.

Deactivates logging and releases the contents and storage space of the AUDIT table as well as that of any existing save table (see the

SAVE operand).

Deactivates logging but retains the AUDIT table and any existing save table (discontinue). DISC can only be used for SCOPE=TASK, where neither the TID nor the TSN operand may be specified.

Outputs the 256-byte table to SYSOUT. The entries in it appear in reverse chronological order, i.e. the last entry is displayed first.

DISPLAY must not be specified in conjunction with the TID or

TSN operand.

Outputs the 256-byte table to SYSLST. The entries appear in reverse chronological order, i.e. the last entry is displayed first.

DUMP must not be specified in conjunction with the TID or

TSN operand.

Writes the 256-byte table to the memory area identified by the virtual address specified in the TABLE operand. The entries appear in reverse chronological order, i.e. the last entry is displayed first.

GET must not be specified in conjunction with the TID or TSN operand.

Creates a save table in the privileged class 5 memory of the task being logged (in addition to the 256-byte table). This save table can be up to 64 Kb in size and increases the amount of AUDIT information that can be recalled accordingly. Entries in the 256-byte table are saved here before being overwritten.

Save tables are also overwritten cyclically and - like foreign task tables - can only be output with the Advanced Interactive Debugger

AID or by means of a dump.

U3586-J-Z125-7-7600

AUDIT

SCOPE

=FUNCT

=TASK

TABLE

=X’addr’

TID

=tid

The SAVE operand is only effective in connection with ACTION=ON and only if AUDIT was previously deactivated with ACTION=OFF, i.e.

if no AUDIT table exists. The size of the save table can thus be changed only via a task-wide deactivation and reactivation of the

AUDIT function.

Number of 4-Kb pages defining the size of the save table.

The maximum size of the save table is 64 Kb (0 n 16 ).

Default value: n=0, i.e., no save table is generated.

Indicates the program area to be logged. The area to be be logged

(AUDIT command) begins at the position where the program is interrupted by an (interrupt) command and the AUDIT command is issued. Logging begins at the point the program run is continued

(RESUME command) and covers the entire (remaining) program run

(SCOPE=TASK) or only the process which has just been interrupted

(SCOPE=FUNCT). In the latter case, it is the basic process or a contingency process.

An AUDIT job for a larger program area or a higher PCB replaces that of a smaller program area or a lower PCB (TASK replaces

FUNCT etc.), but not vice versa.

Specifies that only the process which has just been interrupted is to be logged. FUNCT is only allowed for the user-own task.

Indicates that the requesting task or the task specified in the TID or

TSN operand is to be logged; default value.

Specifies the address of the area to which the contents of the AUDIT table are to be copied. The TABLE operand is ignored if GET=YES is not specified.

Virtual memory address consisting of 1 to 8 hexadecimal digits. The address must refer to an assigned memory area for which write access is authorized (only for P1). The address "0" is invalid. Only the last six digits are relevant in 24-bit addressing mode; in 31-bit addressing mode, all eight digits are relevant. The addressing mode of the program to be logged applies.

Only valid for SCOPE=TASK. Indicates the task to be logged.

h[hhhhhh] Internal task number (1-8 hexadecimal digits, padded to

8 positions by the system with leading zeros if required).

U3586-J-Z125-7-7600

TSN

=tsn

AUDIT

Only valid for SCOPE=TASK. Indicates the task to be logged.

Job number (TSN). It may be supplied in any of the following forms: n[nnn]: a[aaa]:

C’a[aaa]’:

1-4 digits, padded to a 4-digit number by the system with leading zeros if required.

1-4 alphanumeric characters, padded by the system to a 4-digit hexadecimal number with leading zeros as required.

1-4 characters, padded by the system to four positions with leading zeros if required (leading blanks entered by the caller are retained).

If neither the TID nor TSN operand is specified, the requesting task itself is logged.

U3586-J-Z125-7-7600

BCNTRL

BCNTRL Suppress operator messages

Command description

The BCNTRL command allows a user to suppress (for his job) the display of operator messages which are sent by the operator via MESSAGE or BROADCAST commands.

The default value for the first call in a task is the operand value YES. Thereafter, on each subsequent call, the default value used will be that of the last operand specified.

At least one operand must be specified, however.

Urgent messages such as system shutdown messages will nevertheless be output to

SYSOUT.

Format and operand description

Operation

BCNTRL

Operands

YES

MES=

YES

[,BCST=

]

YES

BCST=

[,MES=

YES

]

MES

=YES

=NO

BCST

=YES

=NO

All operator texts sent for this job by the MESSAGE command will be received on SYSOUT. YES is the default value for the first call in a task.

No texts sent by the MESSAGE command will be output to

SYSOUT.

All operator texts sent by the BROADCAST command will be received on SYSOUT. YES is the default value for the first call in a task.

No texts sent by the BROADCAST command will be output to

SYSOUT.

U3586-J-Z125-7-7600

BCNTRL

Example:

The command

/BCNTRL BCST=NO suppresses only those messages which are sent by the operator via the BROADCAST command. Messages sent by the operator via the MESSAGE command are handled according to the default value for MES=....

U3586-J-Z125-7-7600

BREAK

BREAK Request system mode

Command description

The BREAK command can only be issued in a batch job or a procedure.

It interrupts a program which is waiting for data, and enables command input. The

RESUME command may be used to return to program mode. The change of mode is procedure-internal (the procedure level is retained).

Procedure file

/PROQM287039 .....

/SYSFILE SYSDTA=(SYSCMD)

/.........

/EXEC ....

data data

/BREAK

........... .

/SYSFILE SYSDTA=DAT.FILE

/.......

/RESUME

........... .

/ENDP

Command mode

Program mode

Data? (/BREAK)

Fig. BREAK-1 Application of the BREAK command

The BREAK command is ignored if entered in system mode; a message is displayed.

Format

Operation

BREAK

Operands

U3586-J-Z125-7-7600

BREAK

Examples:

In a procedure file, the SYSFILE command is used to assign the (system) files SYSDTA and SYSCMD to the same file. The U.LOAD program, which reads in data from

SYSDTA, is then called:

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

Procedure file:

/PROC C

/SYSFILE SYSDTA=(SYSCMD)

/EXEC U.LOAD

123

459 Data for U.LOAD program

/BREAK

/SYSFILE SYSDTA=U.LOAD.DATA

/RESUME

/ENDP

(01)

(01) Data input is interrupted by the BREAK command and control passes to command mode. The SYSFILE command then assigns system file SYSDTA to the file U.LOAD.DATA. The RESUME command causes the program to be continued. The data for program U.LOAD is then obtained from the file

U.LOAD.DATA, as shown in the following runtime log:

Runtime log:

PROC A

SYSFILE SYSDTA=(SYSCMD)

EXEC U.LOAD

% BLS0500 PROGRAM ’RDATA’, VERSION ’ ’ OF ’86-05-16’ LOADED.

123

123 ****** DATA READ IN ******

459

459 ****** DATA READ IN ******

BREAK

SYSFILE SYSDTA=U.LOAD.DATA

RESUME

567 ****** DATA READ IN ******

489 ****** DATA READ IN ******

ENDP

U3586-J-Z125-7-7600

CALL

CALL Initiate procedure file

Command description

The CALL command is used to initiate a command sequence stored in a file (procedure file). The procedure file is opened, and the command sequence is then processed.

During execution, the symbolic operands contained in the file are replaced with the current operand values specified in the command call. This operation is called a CALL procedure.

Procedure files are SAM or ISAM files with variable record length (RECFORM=V). A procedure file is stored as a cataloged (also temporary) file, as a J-type member in a program library (LMS library routine).

Passwords (CATALOG passwords) can be used to protect procedure files from unauthorized reading (RDPASS), ovwerwriting (WRPASS) and execution (EXPASS). The

EXPASS password or a higher-ranking password must be specified by means of the

PASSWORD command before the CALL command is issued.

If a library member is used as a procedure file, a temporary SAM file is created. This file contains the following member:

S.IN.library.member.tsn.date.hhmmss

where: library = library name (max. 20 characters are printed) tsn = job TSN date = date hhmmss = time-of-day in hours-minutes-seconds

This temporary file is automatically deleted when the following commands are used:

/LOGOFF in the ENTER file

/ENDP in the DO or CALL command

If the CMD macro is used to invoke the CALL command, the calling program is unloaded. Any ABEND-STXIT routine defined in the program is not activated (CMD macro, ABEND-STXIT routine, see "Executive Macros" manual [5]).

The first record in a procedure file is the PROCEDURE command. Subsequent records include commands or data. The last record is the ENDP command (Fig. CALL-1). The

PROCEDURE, LOGON or RESTART must not be specified between these records.

Otherwise the system issues an error message and processes the next command.

U3586-J-Z125-7-7600

CALL

Symbolic operands (e.g. "&X", see example 3) can be used in any position in all the procedure files commands. Current operand values are also substituted for the symbolic operands in the TYPE, PAUSE and REMARK commands. When the processed procedure records are logged to the SYSOUT system file, symbolic operands are replaced by the current operand values.

When the CALL command is issued, the procedure file is assigned to the (system) file

SYSCMD. If data is also to be read from the procedure file, you must equate the system files SYSDTA and SYSCMD in the procedure file. [Command: /SYSFILE

SYSDTA=(SYSCMD)].

A procedure file with data records must contain the /SYSFILE SYSDTA=(SYSCMD) command (before the data) (see SYSFILE command).

It is not necessary to repeat this assignment within a nesting.

In a batch job, any existing assignment at procedure level 0 is also included in the next procedure level.

U3586-J-Z125-7-7600

CALL

Nesting of procedures

Any command procedures can be nested.

Nesting means:

Processing of the commands in a procedure file is interrupted by another procedure file call. Once the ENDP command has been reached, the remaining commands of the last procedure file to be left are processed.

The difference between the CALL procedure and the DO procedure is in the way nested commands are processed (Fig CALL-1): once the ENDP command has been reached, the next command to be read is the one following the last CALL command.

This is also applicable when DO and CALL procedures are mixed.

Fig. CALL-1 Nesting of CALL procedures

U3586-J-Z125-7-7600

CALL

Format and operand description

Operation

CALL

Operands pathname[, sympar=[paramvalue]

[sympar=]paramvalue

,...] pathname catid userid filename library

(member) sympar filename stands for: [:catid:][$userid.] library(member)

Catalog ID of the pubset on which the file is stored.

Default value: the catalog ID assigned to the user ID (JOIN entry).

User ID to which the file is assigned.

Default value: the user ID from the LOGON command.

Name of a cataloged file (the procedure file).

"filename" can also be the name of a temporary file (see also the manual "DMS Introductory Guide and Command Interface" [8]).

The name of a file generation or file generation group may not be specified.

Name of an LMS disk library containing the member "member" (see also the "LMS" manual [14]).

Name of a (J-type) member in the library.

"member" consists of up to 38 characters: alphabetical characters special characters numeric characters

A, ... Z

$, #, -, @

0, ... 9

The first character must be a letter. The last character must not be a hyphen.

The expression "library(member)" can be up to 41 characters long (including parentheses). "library" or "member" can be up to 38 characters long.

Name of a symbolic keyword operand declared in the PROCEDURE command of the procedure file, but without the initial character "&".

U3586-J-Z125-7-7600

CALL

paramvalue Current value of a keyword operand declared in the PROCEDURE command (up to 254 characters long) or a positional operand.

The current operand values "paramvalue" from the CALL command replace the symbolic operands in the PROCEDURE command as follows:

Keyword operands are given the current value from the operand list of the CALL command. If this value is missing, the operand value specified in the PROCEDURE command is used. If this value is also missing or if the keyword was specified in the CALL command without a value, the value is requested interactively, but not before the procedure is run. This last possibility is known as "prompting".

These three possibilities are shown in the following table:

Entry in

CALL cmd.

X=DEF none

Entry in PROCEDURE command

&X=ABC &X=

Prompting

DEF

ABC

Prompting

DEF

Prompting

Positional operands receive in succession the operand values from the CALL command which are specified without the

"sympar=" keyword. If the current value of a positional operand

(indicated by commas) is missing in the CALL command, it is requested interactively during the procedure run (prompting), provided the value is required at all.

Character strings enclosed in single quotes are also allowed as current operand values. Any single quotes in these strings must be entered twice, one after the other.

An empty string (null string) is interpreted as a missing operand value; in interactive mode this causes a request for the operand value during procedure execution.

U3586-J-Z125-7-7600

CALL

If the current value of a parameter is requested during procedure execution, and the user presses the K2 key, the system will respond with "

Terminate procedure ? Yes/No

". If "Yes" is specified, the operating system will insert an ABORT command and terminate the procedure; specifying "No" will repeat the request for the current value of a parameter.

If the question "

Terminate procedure ? Yes/No

" is answered with

"Yes" while a program is loaded, the inserted ABORT will be interpreted as a program statement and result in an error message with regard to the program run. However, this will not cause the procedure to be terminated.

The list of keyword operands and/or positional operands may be enclosed in parentheses (compatibility).

If a command to be executed is to be passed, the slash must already be in the procedure file.

CALL

Examples

Example 1

The following commands are contained in a file named PROC.1:

/PROC C

/ERASE *

/STEP

/SYSFILE SYSDTA=PRIM.ASS

/EXEC $ASSEMB

/ENDP

If the command sequence in this procedure file is initiated with the command /CALL

PROC.1, the commands are processed in the specified order.

The following listing results:

(IN)

(OUT)

(IN)

PROC C

ERASE *

STEP

SYSFILE SYSDTA=PRIM.ASS

EXEC $ASSEMB

% BLS0500 PROGRAM ASSEMB, VERSION 291 OF 84-09-10 LOADED.

V29.1A01 OF SIEMENS BS 2000 ASSEMBLER READY

GIVE ASSEMBLER OPTIONS !

PROCEDURE LEVEL NUMBER 1

SYSDTA : PRIM.ASS

FLAGS IN 00000 STATEMENTS, 000 PRIVILEGED FLAGS, 000 MNOTES

HIGHEST ERROR-WEIGHT : -

SYSTEM MACROLIBRARY : MACROLIB

ASSEMBLY TIME : 1.3308

SEC.

ENDP

Example 2

/PROC C,(&N), SUBDTA=&

/ERASE *

/STEP

/SYSFILE SYSDTA=&N

/EXEC $ASSEMB

/ENDP

A symbolic parameter &N (positional operand) is defined in procedure file PROC.2.

a) The value of the parameter &N is defined when the procedure is called by means of the CALL command:

(IN) CALL PROC.2,(TRE.PRIM.ASS)

U3586-J-Z125-7-7600

CALL

Runtime log:

(IN)

PROC C,(&N)

ERASE *

STEP

SYSFILE SYSDTA=TRE.PRIM.ASS

(IN) EXEC $ASSEMB

(OUT) % BLS0500 PROGRAM ASSEMB, VERSION 291 OF 84-09-10 LOADED.

(OUT) V29.1A01 OF SIEMENS BS 2000 ASSEMBLER READY

(OUT) GIVE ASSEMBLER OPTIONS !

(OUT) PROCEDURE LEVEL NUMBER 1

SYSDTA : PRIM.ASS

(OUT) FLAGS IN 00000 STATEMENTS, 000 PRIVILEGED FLAGS, 000 MNOTES

(OUT) HIGHEST ERROR-WEIGHT : -

(OUT)

(IN)

ASSEMBLY TIME :

ENDP

1.3327

SEC.

A CALL command with the positional operand enclosed in single quotes has the same effect:

/CALL PROC.2,(’TRE.PRIM.ASS’) b) The value of the parameter &N is not defined in interactive mode until the procedure is being executed:

(IN) CALL PROC.2

Runtime log:

(IN)

PROC C,(&N)

ERASE *

STEP

SYSFILE SYSDTA=&N

(OUT) &N=

(IN) PRIM.ASS

(IN)

SYSFILE SYSDTA=PRIM.ASS

EXEC $ASSEMB

(OUT) % BLS0500 PROGRAM ASSEMB, VERSION 291 OF 84-09-10 LOADED.

(OUT) V29.1A01 OF SIEMENS BS 2000 ASSEMBLER READY

(OUT) GIVE ASSEMBLER OPTIONS !

(OUT) PROCEDURE LEVEL NUMBER 1

SYSDTA : PRIM.ASS

(OUT) FLAGS IN 00000 STATEMENTS, 000 PRIVILEGED FLAGS, 000 MNOTES

(OUT) HIGHEST ERROR-WEIGHT : -

(OUT) SYSTEM MACROLIBRARY : MACROLIB

(OUT) ASSEMBLY TIME : 1.3319

SEC.

(IN) ENDP

U3586-J-Z125-7-7600

CALL

Example 3

/PROC C, (&COMP=ASSEMB)

/ERASE *

/STEP

/SYSFILE SYSDTA=U.TEST

/EXEC $&COMP

/ENDP

In procedure file PROC.3

a symbolic parameter &COMP

(keyword parameter) is defined as having the default value ASSEMB.

a) The following CALL command renders the default value for the &COMP parameter effective:

/CALL PROC.3

b) The following CALL commands substitute the default value ASSEMB for FOR1:

/CALL PROC.3,(COMP=’FOR1’) or

/CALL PROC.3,(COMP=FOR1) c) The value of &COMP is requested interactively at procedure execution:

/CALL PROC.3,(COMP=)

The listings generated correspond to those in example 2.

Example 4

In procedure file PROC.4, a parameter list with positional and keyword parameters is defined:

/PROC C,(&N,&COMP=ASSEMB,&ERRFIL=NO,&RD=NONE,&SYMDIC=NO,&LIST=NO,&LOAD),-

/SUBDTA=&

/ERASE *

/STEP

/PARAM ERRFIL=&ERRFIL,SYMDIC=&SYMDIC,LIST=&LIST

/SYSFILE SYSDTA=&N

/EXEC $&COMP

/SYSFILE SYSDTA=(SYSCMD)

/EXEC $TSOSLNK

PROG X,FILENAM=&LOAD,IDA=Y

INCLUDE *

END

/CATALOG &LOAD,STATE=UPDATE,RDPASS=&RD

/ERASE *

/ENDP

U3586-J-Z125-7-7600

CALL

Three of the many ways in which this procedure file can be called are shown below: a) The two positional parameters &N and &LOAD are defined interactively during execution of the procedure; the keyword parameters are assigned default values:

(IN) CALL PROC.4

Runtime log:

(IN)

(OUT

(IN)

PROC C,(&N,&COMP=ASSEMB,&ERRFIL=NO,&RD=NONE,&SYMDIC=NO,-

&LIST=NO,&LOAD),SUBDTA=&

ERASE *

STEP

PARAM ERRFIL=NO,SYMDIC=NO,LIST=NO

SYSFILE SYSDTA=&N

&N=

PRIM.ASS

SYSFILE SYSDTA=PRIM.ASS

EXEC $ASSEMB

(OUT) % BLS0500 PROGRAM ASSEMB, VERSION 291 OF 84-09-10 LOADED.

(OUT) V29.1A01 OF SIEMENS BS 2000 ASSEMBLER READY

(OUT) GIVE ASSEMBLER OPTIONS !

(OUT) PROCEDURE LEVEL NUMBER 1

SYSDTA : PRIM.ASS

(OUT) FLAGS IN 00000 STATEMENTS, 000 PRIVILEGED FLAGS, 000 MNOTES

(01)

(OUT) HIGHEST ERROR-WEIGHT : -

(OUT) SYSTEM MACROLIBRARY : MACROLIB

(OUT) ASSEMBLY TIME :

(IN) SYSFILE SYSDTA=(SYSCMD)

1.5334

SEC.

(IN) EXEC $TSOSLNK

(OUT) % BLS0500 PROGRAM TSOSLNK, VERSION 19.0C00 OF 85-05-08 LOADED.

(IN) PROG X,FILENAM=&LOAD,IDA=Y

(OUT) @LOAD=

(IN) LOAD.ASS

(OUT) % LNK0500 PROG BOUND

(IN)

CATALOG LOAD.ASS,STATE=UPDATE,RDPASS=NONE

ERASE *

ENDP

(01) The continuation character "-" can be located anywhere provided the system parameter SSMCOPT=Y was set at system generation time. If SSMCOPT=N was set, the continuation character must be in column 72.

The declaration @LOAD=LOAD.ASS is not made for the command mode but for the program TSOSLNK.

U3586-J-Z125-7-7600

CALL

b) The linked program &LOAD is to be processed by the Interactive Debugging Aid and receives the name LOAD.IDA:

/CALL PROC.4,(,LOAD.IDA,SYMDIC=YES)

The name of the source program "&N" is requested at procedure execution time.

c) The U.ASS10 source program is to be assembled and the linked PRO10 program protected by the read password C’%%’.

/CALL PROC.4,(U.ASS10,COMP=ASSEMB,RD=C’%%’,PRO10)

The read password can, for example, also be declared in the form RD=’C’’%%’’’.

Example 5

A procedure file FN1 is to call an additional procedure file FN2 (see also the ENDP command).

File FN1 File FN2

/PROC C,(&P1=A)

.................

/CALL FN2,(P2=&P1)

/PROC C, (&P2=C)

/......

/SYSFILE SYSDTA=&P2

/......

/ENDP

&P2 assumes the value of &P1.

Example 6

a) A procedure file P starts with the following PROCEDURE command:

/PROC C, (&P1,&S2=V2,&P3)

In the following calls, some parameters have been omitted. Their current values are requested interactively (prompting) during procedure execution.

Calls for procedure file P

/call p,(a1,s2=a2,a3)

/call p,(a1,s2=a2,)

/call p,(a1,,s2=a2)

/call p,(,,s2=a2)

/call p

Result no prompting prompting for P3 prompting for P3 prompting for P1, P3 prompting for P1, P3

U3586-J-Z125-7-7600

b) The prompt mode can also be used for keyword operands. If procedure file P starts with the PROCEDURE command:

/PROC C, (&P1, &S2=,&P3) then prompting is necessary for keyword operand &S2 in instances such as the calls below.

Call for procedure file P

/call p,(a1,a3)

/call p

Result prompting for S2 prompting for P1, S2, P3

For further examples, see the PROCEDURE, ENDP, ESCAPE and RTI commands.

CALL

U3586-J-Z125-7-7600

CANCEL

CANCEL Cancel job

Application group: File transfer (FT) (see page 37)

Command description

The CANCEL command cancels jobs running under the user’s own own user ID.

However, the calling job is not allowed to cancel itself (this is only possible with the

LOGOFF or ABEND command). The job to be cancelled is identified by its task sequence number (TSN) or a monitoring job variable.

CANCEL, like LOGOFF and ABEND, releases the resources assigned to the task and outputs SYSLST/SYSOPT to printer.

If the job to be cancelled is terminating or has already terminated, the CANCEL command will be rejected and a corresponding message displayed at the terminal.

The CANCEL command will only cancel a job when it is in the TU state (user state) or is waiting for input of a new command.

With spoolout tasks, it is possible for two or more jobs to have the same task sequence number (TSN), e.g. as the result of a PRINT command for a number of files.

In this case, the CANCEL command will affect all jobs with the TSN specified in the command.

A job cannot be cancelled if: it is abnormally terminated due to a system error; it is in the "permanently pended" state; a NCHOLD command was issued for the task (by the operator or system administrator); it has already reached the termination stage; e.g. actions following LOGOFF or

ABEND command/macro, actions in the user program after the ABEND event has been reported (ABEND-STXIT routine, see the "Executive Macros" manual

[5]).

Format and operand description

Operation

CANCEL

CAN

Operands tsn

MONJV=jvname

[,DUMP][,NOSPOOL]

U3586-J-Z125-7-7600

CANCEL

tsn

DUMP

TSN of the job to be cancelled.

Leading zeros need not be specified.

Causes a dump to be output to disk for the job to be cancelled.

However, this will only take place if previously specified in the

OPTION command by selecting one of the following:

OPTION DUMP=YES Dump is output.

OPTION DUMP=STD Dump prompt is displayed; if the response is

"Y", a dump is output.

OPTION DUMP=NO Dump is suppressed.

MONJV=jvname Supplies the name of a job variable defined in the LOGON or

ENTER command for the job to be cancelled.

The status indicator of this job variable is set to "$A". If a program running within this job is being monitored by a job variable, the status indicator of the job variable performing this function is also set to "$A".

If "jvname" is not being used for monitoring a job or is not accessible, the command is rejected.

This operand is only available with the JV software product

(see the "Job Variables" manual [11])

NOSPOOL The system files SYSLST, SYSOUT (if MSG=H in LOGON or

OPTION command) and SYSOPT are not output to printer/punch.

U3586-J-Z125-7-7600

CANCEL

Examples

Extract from an interactive job with the job number (TSN) 1MEV:

(OUT)

(IN)

(OUT)

(IN)

(OUT)

*****

(IN)

(OUT)

Example 1:

(IN)

(OUT)

Dialog from terminal A

STATUS LIST

NAME TSN TYPE

ABCDEFG 1MHT 3 DIALOG

ABCDEFG 1MEV 3 DIALOG

PRI

0 210

CPU-USED CPU-MAX ACCOUNT#

0.2038

2.9835

% SPS0171 NO LOCAL SPOOLOUT JOB PRESENT

% SRO0376 NO RSO JOB OF TYPE=7 PRESENT

9999 ACC12345

CANCEL 1MHT

% EXC0119 CANCEL PROCESSING INITIATED FOR TSN ’1MHT’, USERID ’ID9101’

STATUS LIST

NAME TSN TYPE

ABCDEFG 1MEV 3 DIALOG

PRI

0 210

CPU-USED CPU-MAX ACCOUNT#

3.0581

% SPS0171 NO LOCAL SPOOLOUT JOB PRESENT

9999 ACC12345

% SRO0376 NO RSO JOB OF TYPE=7 PRESENT

Display at terminal B ***** (02)

LOGOFF "JOB CANCELLED"

% NRTT201 TASK TERMINATION DUE TO /CANCEL(-JOB) COMMAND

% EXC0419 /LOGOFF AT 0901 ON 91-01-11 FOR TSN ’1MHT’

% EXC0421 CPU TIME USED: 0.2241 , SERVICE UNITS: 000000000002050

Example 2:

(IN)

(OUT)

Cancel own dialog

CANCEL 1MEV

% EXC0124 USER CANNOT ABORT HIS OWN TASK WITH /CANCEL-JOB

OR /CANCEL. CMD REJECTED (03)

U3586-J-Z125-7-7600

CANCEL

Example 3: ENTER with MONJV

(IN)

(OUT)

(IN)

(OUT)

ENTER ENTER.1,MONJV=MONJV (04)

% JMS0066 JOB ’ENTERDIA’ ACCEPTED ON 90-12-18 AT 09:50, TSN = 0X6B

(05) STATUS MONJV=MONJV

TSN:

JOBNAME: ENTERDIA

USERID:

ACCNB:

0X6B

USR123

ACCXYZ12

TYPE:

PRI:

2 BATCH

9 230

JCLASS: JCB05000

CPU-MAX: 5000

REPEAT: NO

MRSCAT:

TID: 0002012B

RERUN:

HOLD:

UNP/Q#:

17/012

NOW: 901218.095048

SPOOLIN: 901218.0950

LOGON: 901218.0950

CPU-USED:000000.2356

FLUSH:

START:

CMD:

SOON

WAIT

(IN)

(OUT)

CANCEL MONJV=MONJV (06)

% EXC0119 CANCEL PROCESSING INITIATED FOR TSN ’0X6B’, USERID ’USR123’

(01) Use the STATUS command to obtain information on the jobs currently running under your user ID.

(02) The following messages are displayed on the terminal associated with interactive job 1MHT ("forced LOGOFF"):

(IN)

(OUT)

LOGOFF "JOB CANCELLED"

% NRTT201 TASK TERMINATION DUE TO /CANCEL(-JOB) COMMAND

% EXC0419 /LOGOFF AT 0901 ON 91-01-11 FOR TSN ’1MHT’

% EXC0421 CPU TIME USED: 0.2241 , SERVICE UNITS: 000000000002050

(03) You cannot use CANCEL to cancel your own job.

(04) The ENTER initiates batch job 0X6B. This job is to be monitored by job variable

MONJV.

(05) The STATUS command requests information about the batch job monitored by

MONJV.

(06) The CANCEL command terminates the batch job 0X6B monitored by MONJV.

U3586-J-Z125-7-7600

CANCEL-FILE-TRANSFER

CANCEL-FILE-TRANSFER Cancel file transfer

This command is only available with the software product FT.

Command description

The CANCEL-FILE-TRANSFER command allows the processing of one or more FT jobs to be aborted.

Subsets of existing FT jobs can be selected by specifying selection criteria.

The following command description covers only the abbreviated command format. (The description is valid for FT-BS2000 V4.0B.) Refer to the "File Transfer" manual [7] for a detailed description with application examples.

Format (abbreviated format) and operand description

Operation

CANCEL-FILE-

TRANSFER

NCANCEL

Operands

[TRANS=

*ALL no

]

*OWN

[,SELECT= (*LOCAL,*REMOTE)

(INIT= *LOCAL

*REMOTE

[,PARTNER=

*ALL name

]

*ALL

[,FILE-NAME= *LIB(LIB=

*ALL lib } filename

,ELEM=

*ALL member

(VERS=

*ALL version

),TYPE=

*ALL type

]

[,MONJV=

*NONE jvname

*NONE

],[JV-PASS= password ]) ]

*SECRET

U3586-J-Z125-7-7600

CANCEL-FILE-TRANSFER

TRANS

=*ALL

=no

SELECT={...}

Identifies the FT job to be aborted.

All your FT jobs will be aborted; default value.

FT job number (transfer ID).

*OWN

Permits selection of a subset of FT jobs. All selection criteria specified must be valid for the job to which they apply. Processing of the selected FT jobs is aborted.

All your FT jobs are aborted; default value.

INIT

=*LOCAL

=*REMOTE

Permits selection of FT jobs started in the local or a remote system.

The local system is the system where the CANCEL-FILE-TRANSFER command is issued.

=(*LOCAL,*REMOTE)

Selects all FT jobs started in the local or a remote system; default value.

Selects all jobs started in the local system.

PARTNER

Selects all jobs started in the remote system.

Permits selection of FT jobs processed in cooperation with the specified partner system.

=*ALL

=name

FILE-NAME

=*ALL

Jobs are selected without regard to the partner system, if any; default value.

Name of the partner system.

Permits selection of FT jobs accessing the specified file/ library. The file/library must be cataloged in the local system.

Jobs are selected without regard to the name of the file/ library; default value.

=*LIB(...)

*ALL

Refers to FT jobs accessing a particular library. The selection can be further restricted by specifying a library name/member name/member version/member type.

Jobs are selected without regard to the library name/member name/member version/member type.

lib library name member member name version version name

U3586-J-Z125-7-7600

CANCEL-FILE-TRANSFER

type

=filename

MONJV

=*NONE member type

File name

Permits selection of FT jobs monitored by a job variable.

Jobs are selected without regard to the monitoring job variable, if any.

=jvname

JV-PASS

Name of the job variable.

Specifies the password, if any, that protects the job variable.

=*NONE No password has been defined.

=password Password protecting the job variable.

=*SECRET The system prompts the user to enter a password. Display of the password on the screen is suppressed when you enter it.

U3586-J-Z125-7-7600

CATALOG

CATALOG Process catalog entry

Application groups:

File processing (page 26 ff.)

Device and volume reservation (page 29)

FGG = file generation group; FG = file generation

Command description

The CATALOG command is used to catalog a file or file generation group or to modify the file names and protection attributes for a cataloged file/FGG.

The following can be defined: file name read/write access allowed shareability read, write and execute passwords write protection save frequency and type of save (full etc.) with the ARCHIVE file saving system data protection (data destruction) access monitoring by means of DMS routines (AUDIT function) migration by HSMS permitted or not permitted

The CATALOG command can also be used to create the catalog entry for a temporary

(user) file or to convert a temporary file into a permanent file, and vice versa. The following restrictions apply to temporary files:

The RETPD operand has no effect.

The following system default values apply: RDPASS=NONE, WRPASS=NONE,

EXPASS=NONE, SHARE=NO, ACCESS=WRITE and BACKUP=E; (SHARE=YES for tape files). These values cannot be changed.

The following applies when recataloging files from temporary to permanent: the file attributes of the temporary files are retained (exception: the default value is assumed for BACKUP).

When files are recataloged from permanent to temporary, the default attributes for temporary files are used.

Default values are available for all operands when the catalog entry for a file is created

(see the description of the operands).

U3586-J-Z125-7-7600

CATALOG

File generation groups (FGG)

If you wish to work with a file generation group (FGG), the group entry must be created before the first generation is cataloged. Unlike files and file generations, which can also be cataloged using the FILE command, the group entry can be only created with the CATALOG command.

Files can be recataloged as file generations providing the file generations are recreated when this is done. However, file generations cannot be recataloged as files.

File generation groups which are stored on private disks and for which no catalog entries exist are called "foreign" file generation groups. If such FGGs are to be cataloged again, the group entry must be created first. For file generation groups on private disks, the operand STATE=FOREIGN can be used for this purpose if the F1 label on the disk contains the group entry. The system then creates the group entry from the information in the F1 label of the private disk specified via the DEVICE and

VOLUME operands.

For the importation of a file generation group whose generations are stored on tape or on a private disk whose F1 label does not contain the group entry, the operands FIRST and BASE must be specified in the CATALOG command for the group entry.

U3586-J-Z125-7-7600

CATALOG

Files on magnetic tapes and tape cartridges

When creating or updating the catalog entries for tape files, you must observe some special features which result from the use of tapes.

When files with standard labels are created, details of the shareability (SHARE), access type (ACCESS) and passwords are transferred from the catalog entry to the file labels.

If SECLEV=HIGH (see the FILE command) is specified for a foreign file, details of the access rights are transferred from the file labels into the catalog entry when the file is opened.

Since file labels on a tape cannot be changed without destroying the file (this is a hardware restriction), and the contents of the catalog entry for a file must match the contents of the file labels, the access rights and the expiration date of a tape file cannot be changed by means of the CATALOG command once the file has been opened and closed correctly.

If the tape file was cataloged using the FILE command, the file protection attributes can be modified using the CATALOG command before the file is opened for the first time.

These attributes are then transferred without further checking to the file labels when the file is created. In this way, it is possible to define write protection (ACCESS=READ) for a file which is still to be created. The file can then be opened as an output file and created, after which the write protection comes into effective.

If a tape file has been cataloged with FILE, it will be shareable, unless the CATALOG command is specified with SHARE=NO before the file is opened for the first time.

If password protection is specified for a tape file, the label processing routines transfer the passwords to the HDR3 label, without checking them, when the file is created.

Similarly, when a file is imported, passwords are transferred from the HDR3 label into the catalog entry.

The passwords are not transferred for a file for which SECLEV=LOW is specified.

If the system administrator selected password encryption when the system was generated, the encryption indicator in the HDR3 label is set to ’1’ when the file is opened.

The owner of a tape file can bypass checking of the access authorization by specifying

SECLEV=LOW.

U3586-J-Z125-7-7600

CATALOG

Format and operand descriptions

Operation

CATALOG

CAT

Operands pathname1[,filename2]

NEW

[,STATE= UPDATE ][,ACCESS=

FOREIGN

WRITE

READ

][,SHARE= YES

SPECIAL

]

[,WRPASS=

NONE password

NONE

][,RDPASS= password

]

NONE

[,EXPASS= password

][,RETPD=days][,MIGRATE=

ALLOWED

INHIBIT

]

[,BASE=number][,DISP=

CYCLE

REUSE

DELETE

KEEP

][,GEN=number][,FIRST=number]

[,AUDIT=

NONE

ALL

][,VOLUME=vsn][,DEVICE=device]

SUCC

FAIL

[,BACKUP= C ][,LARGE=

YES

][,DESTROY=

YES

]

NONE

STD

OWNER=access-rights

[,BASIC-ACL=

( GROUP=access-rights

OTHERS=access-rights

[, ... ])

]

Unless specified otherwise, the descriptions below apply to files as well as the file generations of a file generation group.

U3586-J-Z125-7-7600

CATALOG

Positional operands

pathname1 stands for: [:catid:][$userid.]filename1 catid userid

Catalog ID of the pubset on which the file is stored. Default value: the catalog ID assigned to the user ID (JOIN entry).

User ID.

Default value: user ID from the LOGON command.

Only the user’s own user ID is allowed.

filename1 filename2

Fully-qualified name of the file for which a catalog entry is to be created or whose file attributes are to be modified. The name of a

file generation (see page 44) may be specified only for the purpose

of creating its catalog entry (operand STATE=NEW); the file attributes are determined by the FGG.

New file name for the file "filename1".

This operand must be entered without the catalog ID and user ID.

The following applies to tape files:

The only permissible "filename2" entry is "filename1" provided with a version identifier in parentheses which must be different from the original version identifier, if any. This restriction is a result of tape label processing: individual blocks of the tape file cannot be overwritten for hardware reasons and the file name in the label is compared with the file name in the catalog entry when the file is opened.

Example:

/CAT TAPE,TAPE(ONE),STATE=UPDATE

/CAT TAPE(120),TAPE(40),STATE=UPDATE

U3586-J-Z125-7-7600

CATALOG

Keyword operands (in alphabetical order)

ACCESS Specifies whether only read access or both read and write access is allowed for the file.

Tape files: the ACCESS indicator is copied to the HDR3 label by

DMS when the file is opened for the first time. The file owner can specify SECLEV=LOW in order to bypass access mode checking for subsequent file accesses (see the FILE command).

=WRITE

=READ

Both read and write accesses are allowed (write access implies read access). WRITE is the default value for a file to be newly cataloged.

Tape files: HDR3 label access type = 0

Specifies that only read access is permitted.

Tape files: HDR3 label access type = 1

AUDIT

=SUCC

=FAIL

=ALL

=NONE

Permits the logging of file accesses by system exit routines.

CATALOG, ERASE, FILE and OPEN operations can be audited. This file access logging facility can be restricted to particular user IDs by the AUDIT operand in the JOIN command (see the "System

Administrator’s Guide" [1]).

All successful DMS actions for the file are to be audited.

All unsuccessful DMS actions for the file are to be audited.

All DMS actions for the file are to be audited.

No auditing. NONE is the default value when creating the catalog entry.

BACKUP

Specifies the frequency with which the file is to be saved with the regular save runs performed by the ARCHIVE file saving system. The function is performed for disk files only.

The default value for BACKUP is specified by the system administrator at system generation and is only effective in conjunction with STATE=NEW.

The file is saved in every save run.

The file is saved whenever a save run for files with BACKUP=B/C/D is performed.

The file is saved whenever a save run for files with BACKUP=C/D is performed.

The file is only saved when a save run for files with BACKUP=D is performed.

No automatic saving by ARCHIVE.

U3586-J-Z125-7-7600

BASE

=number

BASIC-ACL

=NONE

CATALOG

For file generation groups only: defines a reference point or base generation for relative generation numbers.

Default value: value of the FIRST operand when the FGG is created, or BASE=0 if no FIRST value is specified.

If generations of an FGG for which no group entry exists in the catalog or in the F1 label of the disk are imported from a private disk, the BASE operand must be specified in the CATALOG command for the group entry.

0 number +9999; "number" is the absolute generation number of the base generation. When creating a group entry (STATE=NEW),

"number" is entered in the catalog as the base value and this base generation becomes the oldest generation (catalog field FIRSTGN). If specified together with STATE=UPDATE, "number" must refer to a generation which is already cataloged; the BASE value in the catalog entry is then updated accordingly.

-99 number -1; "number" is the relative generation number of the new base generation with respect to the most recently cataloged generation (base = LASTGN + number). This relative specification of the base value is permitted only together with STATE=UPDATE (cf.

examples).

Only for permanent files; defines how specific user classes can access the file (see the manual "DMS Introductory Guide and

Command Interface" [8]).

The BASIC-ACL indicator in the catalog entry is reset.

U3586-J-Z125-7-7600

CATALOG

=STD A BASIC-ACL entry is created for the file.

The following default values apply for STATE=NEW (default)

OWNER=(READ=YES, WRITE=YES, EXEC=YES), GROUP=NO

ACCESS, OTHERS=NO ACCESS.

If STATE=UPDATE is specified at the same time, the existing settings for SHARE and ACCESS are transferred as follows:

SHARE ACCESS

WRITE

READ

YES WRITE

YES READ

OWNER GROUP OTHERS

R W X R W X R W X

Y Y Y - - - - -

Y - Y - - - - -

Y Y Y Y Y Y Y Y Y

Y - Y Y - Y Y - Y

=(...) Defines individual access rights for the specified user classes.

OWNER= Defines how the owner may access the file.

GROUP= Defines how members of the owner’s group may access the file.

OTHERS= Defines how members of other groups may access the file.

access rights mean:

NO-ACCESS

[NO]

([READ=

YES

],[WRITE=

[NO]

YES

],[EXEC=

[NO]

YES

])

NO-ACCESSNo access authorization

READ

=NO

=YES

WRITE

=NO

=YES

EXEC

=NO

=YES

Read access

Not allowed;

Allowed;

Write access

Not allowed;

Allowed;

Execute access

Not allowed;

Allowed;

U3586-J-Z125-7-7600

CATALOG

DESTROY

=YES

=NO

Specifies whether or not the file is to be destroyed on deletion.

Whenever a file is released or opened for writing, the storage space occupied by the file is overwritten with X’00’ (data destruction).

Tape files: any data remaining on tape is destroyed when the file is closed.

When the file is deleted, its storage space is returned unchanged to the system unless data destruction was specifically requested in the

ERASE command (DESTROY operand in the ERASE command).

NO is the default value when the catalog entry is created.

Tape files: any data remaining on tape is not destroyed unless

DESTOC=YES was specified in the FILE command.

DEVICE=device Only for file generation groups on private disks; designates the disk device on which the FGG is to be stored. The permissible entries for

"device" are listed in the device table in the appendix.

The VOLUME and DEVICE operands must be specified when an FGG is created on private disk(s) (STATE=NEW) an existing FGG on private disk(s) is to be reconstructed (STATE-

FOREIGN).

Otherwise, specification of VOLUME and DEVICE results in an error message.

DISP

=CYCLE

Only for file generation groups: specifies whether the oldest generations are to be erased and, possibly, their storage space reused when the maximum number of simultaneously existing generations specified with GEN= is exceeded. In the case of generations on tape, only the catalog entry is deleted.

The oldest existing generation is erased and its storage space on disk or the tapes it occupies is/are released. The LASTGN and

FIRSTGN fields in the catalog entry (youngest and oldest existing generations) are updated accordingly; DISP=CYCLE is the default value.

U3586-J-Z125-7-7600

CATALOG

=REUSE

=DELETE

=KEEP

EXPASS

=NONE

The effects of DISP=REUSE vary depending on the type of volume:

For FGGs on public disks: the oldest generation is erased, its storage space is returned to the system, and the group entry is updated (see DISP=CYCLE).

For FGGs on private disks: the new generation is created, the oldest generation is erased, and the volume is used for storing the new generation. If the generation which was deleted extended over several volumes, the new generation is cataloged only on the first of these volumes. The group entry is updated accordingly.

Since the old generation is not erased until the new generation has been created, insufficient space on the volume can prevent creation of the new generation even though

DISP=REUSE is specified.

For FGGs on tape: the oldest generation is deleted from the catalog and the new generation is created on the tapes thereby released.

The group entry is updated accordingly. DISP=REUSE must not be specified for FGGs in file sets.

All generations of the FGG are erased and the new generation becomes the oldest generation of a new series. The group entry is updated accordingly.

The "superfluous" oldest generations are not erased automatically, but only when a CATALOG command with the operands FIRST and

BASE is used to define a new "oldest" and a new base generation, or when a new value is specified for DISP=. As each new generation is created, only the LASTGN field in the group entry is updated.

Defines an execute password to safeguard against unauthorized execution of a load module or of a command sequence (procedure or ENTER task) stored in the file. The password must be entered in the task password table by means of the PASSWORD command before the program or command sequence is executed for the first time. (An execute password includes protection against unauthorized read and write access.) EXPASS must not be specified for an FGG.

No password is declared. NONE is the default value for creating the catalog entry.

U3586-J-Z125-7-7600

CATALOG

=password

FIRST=number Only for file generation groups: specifies the absolute generation number (1 number 9999) of the first file generation to be cataloged. FIRST may thus be specified only when a file generation group is being created (STATE=NEW).

The FIRST operand is needed for reconstruction of the catalog entry of a foreign file generation group which is stored on a private volume, and should be used for this purpose only. File generations stored on tape must be cataloged individually using the FILE command (operand STATE=FOREIGN), while generations stored on private disk can be cataloged by means of the IMPORT command or individually by means of the FILE command (operand

STATE=FOREIGN).

GEN=number

Execute password; specified as a C-string, X-string or decimal number (see the WRPASS operand). If X’00000000’ is specified for

"password", it is ignored.

LARGE

=YES

=NO

Only for file generation groups; 0 number 255; specifies the number of FGG generations that may be cataloged at the same time

(cf. DISP operand). GEN may be specified for a new (STATE=NEW) or an existing file generation group (STATE=UPDATE). Default value:

GEN=0

GEN=0: if it is specified in conjunction with STATE=NEW, a

"normal" file rather than a file generation group is created; if is specified in conjunction with STATE=UPDATE, GEN=0 is ignored.

Determines the type of backup (for disk files only).

In save runs using ARCHIVE, only those PAM blocks which have been modified since the last backup operation are saved. (This is of particular relevance for large files.)

The file is saved in its entirety in every save run using ARCHIVE. NO is the default value when the catalog entry is created.

U3586-J-Z125-7-7600

CATALOG

MIGRATE

=ALLOWED

=INHIBIT

RDPASS

=NONE

=password

RETPD

=days

Only for files and file generations (FGs) on public disks and only relevant in conjunction with HSMS (Hierarchical Storage

Management System). The MIGRATE operand can be used to specify whether files or FGs which have not been used for some time may be migrated from the online storage level to a background storage level with a considerably longer access time. (For more information see the "HSMS" manual.)

Default value:

MIGRATE = ALLOWED for permanent files;

MIGRATE = INHIBIT for temporary files.

The file or file generation (FG) may be migrated from storage level

S0 to level S1 or S2.

The file or file generation (FG) must not be migrated.

Defines a read password to safeguard against unauthorized read access to the file. This safeguarding includes protection against unauthorized write access, but not against execution of an object/load module stored in the file or of a command sequence. In the case of an object/load module, both the file itself and the section currently in main memory are protected against unauthorized read access (the LOAD command and the IDA commands DISPLAY and AT are rejected when access is not authorized). The password must be entered in the task password table prior to the first read or write access by means of the PASSWORD command.

No password is defined. NONE is the default value when creating the catalog entry.

Defines a read password, specified as a C-string, X-string or decimal number (see the WRPASS operand).

Specifies a file retention period in days, during which time the file may only be read, i.e. it cannot be modified or deleted. The retention period can only be defined for files which already exist, i.e.

the operand will be ignored if STATE=NEW is specified. The RETPD operand has no effect on tape files.

Indicates a retention period in days (0..32767). The date on which the retention period ends is computed by the system and noted in the EXDATE field of the catalog entry (see the FSTATUS command).

Default value: days=0, i.e. the file may be updated immediately.

U3586-J-Z125-7-7600

CATALOG

=NO

=YES

=SPECIAL

STATE

=NEW

=UPDATE

=FOREIGN

Specifies whether or not the file is shareable. Shareability means that users with a different user ID can also read the file catalog entry and access the file.

The file is not shareable. NO is the default value when the catalog entry is created.

Tape files: HDR1 label access indicator = 1.

The file is shareable.

Tape files: HDR1 label access indicator = 2.

The file can also be accessed under the $SERVICE ID.

At the same time, SHARE=YES applies.

Specifies whether a new catalog entry is to be created or an existing catalog entry is to be changed.

A new catalog entry is to be created; default value.

An existing catalog entry is to be updated. A catalog field is not updated unless the corresponding operand is specified explicitly; default values apply to a new catalog entry only.

If the file is password-protected, the catalog entry cannot be updated unless the write password is entered. For details about password protection of files please refer to the manual "DMS

Introductory Guide and Command Interface" [8].

Only for non-cataloged FGGs on private volumes; a catalog entry is created for the file generation group stored on private disk. If

STATE=FOREIGN is specified, the operands DEVICE and VOLUME must also be specified; any further operands are ignored. The values for GEN, BASE and FIRST are taken from the F1 label of the private disk and placed in the catalog entry. All generations of the foreign

FGG to be imported must either be indicated to the system individually in a separate FILE command/macro (operands

STATE=FOREIGN, DEVICE and VOLUME, one FILE command/macro for each generation!), or they may be added collectively by means of the IMPORT command.

U3586-J-Z125-7-7600

CATALOG

VOLUME=vsn

WRPASS

=NONE

=password

Only for FGGs on private volumes; specifies the private disk on which the group entry is kept via its volume serial number ("vsn"). All related generations must also be on private disks and must be created by means of FILE commands.

The VOLUME and DEVICE operands must be specified when an FGG is created on private disks (STATE=NEW) an existing FGG on private disks is to be reconstructed (STATE-

FOREIGN).

Otherwise, specification of VOLUME and DEVICE results in an error message.

Defines a write password to protect the file against unauthorized write accesses. Read access is allowed.

If a password has been defined for a file, it must be entered in the task password table prior to the first write access to the file using the PASSWORD command.

No password is defined. NONE is the default value when the catalog entry is created.

Write password; specified as a C-string, X-string or decimal number.

C-string: C ’character-constant’; up to 4 characters.

X-string: X ’hexadecimal-constant’; up to 8 characters.

Decimal number: decimal-constant; permitted range:

-2147483648 through 2147483647.

When a CATALOG command is logged to the system file SYSLST or

SYSOUT, all passwords are overwritten with the letter "P".

U3586-J-Z125-7-7600

CATALOG

Examples

Example 1

: Creating the catalog entry for the file FILE.NEW

(IN)

(OUT)

CATALOG FILE.NEW

FSTATUS FILE.NEW,ALL

00000000 :N:$USR123.FILE.NEU

FCBTYPE = NONE

SHARE = NO

ACL = NO

CRDATE = NONE

RDPASS = NONE

ACCESS# = 000

LARGE = NO

BLKTYPE = NONE

RECFORM = NONE

VSN/DEV/EXT =

:N: PUBLIC:

VSNTYPE = NONE

ACCESS

AUDIT

= WRITE

= NONE

EXDATE = NONE

WRPASS = NONE

VERSION = 000

BACKUP = A

BLKSIZE = 000000

RECSIZE = 000000

NONE

1 FILE RES= 0 FREE=

Example 2

: Defining a read password for the file FILE.NEW

(IN)

(OUT)

CATALOG FILE.NEW,RDPASS=P,STATE=UPDATE

FSTATUS FILE.NEW,ALL

00000000 :N:$USR123.FILE.NEU

FCBTYPE = NONE

ACL

= NO

CRDATE = NONE

RDPASS = YES

ACCESS# = 000

LARGE = NO

BLKTYPE = NONE

RECFORM = NONE

VSN/DEV/EXT =

:N: PUBLIC:

VSNTYPE = NONE

ACCESS

AUDIT

EXDATE

WRPASS

= WRITE

= NONE

VERSION = 000

BACKUP = A

BLKSIZE = 000000

RECSIZE = 000000

NONE

1 FILE RES= 0 FREE=

(01)

DESTROY = NO

LADATE = NONE

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = NONE

0 REL= 0 PAGES

(02)

DESTROY = NO

LADATE = NONE

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = NONE

0 REL= 0 PAGES

U3586-J-Z125-7-7600

CATALOG

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

Example 3:

Creating the catalog entry for a file generation group and its file generations

(OUT)

CATALOG DAT.GROUP,GEN=5,RDPASS=P,BACKUP=C,DESTROY=YES

CATALOG DAT.GROUP(*1)

CATALOG DAT.GROUP(+1)

% DMS05CC FILE NAME ALREADY CATALOGED OR INVALID OPERAND.

(03)

(04)

(05)

COMMAND NOT PROCESSED

CATALOG DAT.GROUP,BASE=1,STATE=UPDATE (06)

% DMS05CF FILE PASSWORD-PROTECTED. ENTER REQUIRED PASSWORD AND REENTER COMMAND

PASSWORD P

CATALOG DAT.GROUP,BASE=1,STATE=UPDATE

CATALOG DAT.GROUP(+1)

CATALOG DAT.GROUP(+2)

CATALOG DAT.GROUP(*3)

% DMS05CC FILE NAME ALREADY CATALOGED OR INVALID OPERAND.

COMMAND NOT PROCESSED

CATALOG DAT.GROUP(+3)

CATALOG DAT.GROUP(+5)

% DMS06C7 INVALID GENERATION NUMBER IN COMMAND. NUMBERS MUST

BE IN UNBROKEN ASCENDING ORDER. COMMAND NOT PROCESSED

CATALOG DAT.GROUP(+4)

CATALOG DAT.GROUP(+5)

FSTATUS DAT.GROUP,GEN=YES,CATALOG

(07)

(08)

00000000 :N:$USR123.DAT.GROUP (FGG)

ACL

= NO

ACCESS

AUDIT

= WRITE

= NONE

CRDATE = 1990-12-18

RDPASS = YES

EXDATE = 1990-12-18

WRPASS = NONE

ACCESS# = 000 VERSION = 000

LARGE = NO BACKUP = C

00000000 :N:$USR123.DAT.GROUP(*0002)

ACL

= NO

ACCESS = WRITE

AUDIT = NONE

CRDATE = NONE

RDPASS = YES

ACCESS# = 000

EXDATE = NONE

WRPASS = NONE

VERSION = 000

LARGE = NO BACKUP = C

00000000 :N:$USR123.DAT.GROUP(*0003)

SHARE = NO

ACL = NO

CRDATE = NONE

RDPASS = YES

ACCESS# = 000

ACCESS

AUDIT

= WRITE

= NONE

EXDATE = NONE

WRPASS = NONE

VERSION = 000

DESTROY = YES

LADATE

EXPASS

= NONE

MIGRATE = ALLOWED

DESTROY = YES

LADATE

EXPASS

= NONE

MIGRATE = ALLOWED

DESTROY = YES

LADATE

EXPASS

= NONE

LARGE = NO BACKUP = C

00000000 :N:$USR123.DAT.GROUP(*0004)

SHARE = NO ACCESS = WRITE

ACL = NO

CRDATE = NONE

AUDIT = NONE

EXDATE = NONE

RDPASS = YES

ACCESS# = 000

LARGE = NO

WRPASS = NONE

VERSION = 000

BACKUP = C

00000000 :N:$USR123.DAT.GROUP(*0005)

SHARE = NO ACCESS = WRITE

ACL = NO

CRDATE = NONE

RDPASS = YES

ACCESS# = 000

LARGE = NO

AUDIT = NONE

EXDATE = NONE

WRPASS = NONE

VERSION = 000

BACKUP = C

00000000 :N:$USR123.DAT.GROUP(*0006)

ACL

= NO

ACCESS

AUDIT

= WRITE

= NONE

CRDATE = NONE

RDPASS = YES

EXDATE = NONE

WRPASS = NONE

ACCESS# = 000

LARGE

:N:

= NO

PUBLIC:

VERSION = 000

BACKUP = C

6 FILES RES= 0 FREE=

MIGRATE = ALLOWED

DESTROY = YES

LADATE

EXPASS

= NONE

MIGRATE = ALLOWED

DESTROY = YES

LADATE = NONE

EXPASS = NONE

MIGRATE = ALLOWED

DESTROY = YES

LADATE

EXPASS

= NONE

MIGRATE = ALLOWED

0 REL= 0 PAGES

(01) The catalog entry for the file FILE.NEW is created. The file attributes

U3586-J-Z125-7-7600

CATALOG

(ACCESS=..., SHARE=..., RDPASS=..., ...) are set to their default values.

(02) A read password is defined. The password is replaced by the letter "P" in the log.

(03) The catalog entry for the file generation group DAT.GROUP is created. Up to five generations can be cataloged with one CATALOG command. A read password is defined. BACKUP=C is specified for file saving; DESTROY=YES provides for data destruction during erasure.

(04) The first file generation is cataloged (specifying the absolute generation number).

(05) The second file generation is cataloged (specifying the relative generation number). An error message is returned because the base value has not yet been defined.

(06) The first file generation is defined as the base generation. The read password must be entered in the task password table (PASSWORD command) before the catalog entry is updated.

(07) An attempt is made to catalog the third file generation, again specifying the absolute generation number. An error message is returned.

(08) A catalog entry for a file generation cannot be created until the predecessor generation has been cataloged.

U3586-J-Z125-7-7600

CATJV

CATJV Catalog job variable

Application group: Job variable functions (page 36)

The CATJV command is only available with the software product JV (see the "Job

Variables" manual [11]).

Command description

The CATJV command allows a job variable entry in the catalog to be created or updated.

Formats and operand descriptions

Given below are the formats and operand descriptions for permanent job variables and temporary job variables.

100

U3586-J-Z125-7-7600

CATJV

Permanent job variables

Operation

CATJV

Operands jvname1 [,jvname2]

[,STATE=

NEW

UPDATE

][,ACCESS=

WRITE

]

READ

[,SHARE=

YES

][,RETPD=days]

[,RDPASS=

NONE password

NONE

][,WRPASS= password

]

UNCHANGED

[,MONJV=

]

NONE

[,BASIC-ACL= OWNER=access rights

( GROUP=access rights [, ... ])

OTHERS=access rights

] jvname1 jvname2

Specifies the fully-qualified name under which the job variable is cataloged. Only the system administrator is allowed to specify the user ID of another user.

Declares a new name for the job variable "jvname1". User ID and catalog ID must not be specified, since this would mean a change of owner or catalog. This operand only takes effect when

"STATE=UPDATE" has likewise been supplied.

"jvname2" may be a temporary or permanent job variable. If

"jvname1" is a permanent job variable, and "jvname2" is a temporary one, the protection attributes must be reset to default values at the same time.

U3586-J-Z125-7-7600

101

CATJV

ACCESS

=READ

=WRITE

Defines possible access to the job variable.

Specifies that the job variable may only be read.

Both read and write access are permitted for the job variable.

BASIC-ACL

=NONE

=(...)

Specifies whether the job variable is to be protected by means of a

BACL entry.

The job variable is not to be protected by a BACL entry.

The job variable is to be protected by a BACL entry.

OWNER=...

Grants the access rights specified below to the owner.

GROUP=...

Grants the access rights specified below to the user’s user group.

OTHERS=...

Grants the access rights specified below to the other user groups.

access-rights mean:

NO-ACCESS

( [READ= ][,WRITE=

YES

NO-ACCESSNo access authorization

YES

])

READ

WRITE

Read access: yes/no

Write access: yes/no

MONJV

=UNCHANGED Specifies that the protection for the monitoring job variable is to remain unchanged.

=NO

Specifies whether or not the monitoring job variable should continue to be protected.

Cancels the system area (bytes 1 through 128) protection of a previous monitoring job variable. This specification is only effective with STATE=UPDATE and, furthermore, only when the job to be monitored no longer exists.

102

U3586-J-Z125-7-7600

CATJV

RDPASS

=NONE

=password

RETPD=days

=YES

=NO

STATE

=NEW

=UPDATE

Defines whether or not the job variable is to be protected by means of a read password. The read password must be an expression one to four characters in length. Character, hexadecimal and integer formats are permitted. A password such as X’00000000’ is ignored.

Indicates that the job variable is not to be protected by a read password, and that any previously defined read password is to be cancelled.

Specifies the read password with which the job variable is to be protected.

Specifies a retention period in days (0...32767), during which the job variable must not be updated or deleted (write protection).

The job variable must already be cataloged; if STATE=NEW is specified at the same time, RETPD is ignored.

Default value: days=0, i.e. the job variable may be updated immediately.

Defines whether foreign user IDs are to be granted access to the job variable.

Specifies that the job variable may be accessed from a foreign user

ID.

Specifies that the right to access the job variable is not to be granted to foreign user IDs. Only the owner or the system administrator may then access the job variable.

Specifies whether a new catalog entry is to be created for a job variable or an existing catalog entry is to be updated.

A new catalog entry is to be created.

An existing catalog entry is to be updated.

Only explicitly specified catalog fields are updated with

STATE=UPDATE. Omitted operands are not set to default values.

U3586-J-Z125-7-7600

103

CATJV

WRPASS

=NONE

Defines whether or not the job variable is to be protected by means of a write password. The write password must be an expression one to four characters in length. Character, hexadecimal and integer formats are permitted. A password such as X’00000000’ is ignored.

Indicates that the job variable is not to be protected by a write password, and that any previously defined write password is to be cancelled.

=password Specifies the write password with which the job variable is to be protected.

For examples see the "Job Variables" manual [11].

104

U3586-J-Z125-7-7600

CATJV

Temporary job variables

Operation

CATJV

Operands

#jvname1[,jvname2]

NEW

[,STATE=

UPDATE

]

#jvname1 jvname2

Name of the temporary job variable to be cataloged.

"#" is the prefix identifying temporary files and job variables; it is defined by the system administrator by means of the system parameter TEMPFILE.

Declares a new name for the job variable "jvname1". User ID and catalog ID must not be specified, since this would mean a change of owner or catalog. This operand only takes effect if

"STATE=UPDATE" has likewise been specified.

"jvname2" may be a temporary or a permanent job variable.

STATE

=NEW

Specifies whether a new catalog entry is to be created or whether an existing one is to be updated.

Creates a new catalog entry under the name

S.TMP.tsn.jvname1

=UPDATE

This is the default value.

Specifies that a temporary job variable is to be renamed.

The unmodifiable protection attributes for temporary job variables are normally set to the following default values:

RETPD=0,RDPASS=NONE,WRPASS=NONE,SHARE=NO,ACCESS=WRITE

A temporary job variable appears in system messages and in the output of SHOW-CJC-

STATUS under its internal name S.TMP.tsn.jvname.

Renaming can be used to convert a temporary job variable into a permanent one.

When a permanent job variable is converted to a temporary one, protection attributes must be reset to default values at the same time.

For examples see the "Job Variables" manual [11].

U3586-J-Z125-7-7600

105

CHANGE

CHANGE Change TFT entry

Application group: Device and volume reservation (page 29)

Command description

The CHANGE command can be used to change the file link name in a task file table

(TFT) entry. All other values in this TFT entry remain unaltered. The command cannot be applied to the TFT entry for an open file.

Format and operand description

Operation

CHANGE

Operands

[link1],link2 link1 link2

Specifies the file link name (1 to 8 bytes).

If this entry is omitted, the first TFT entry with the link name

C’ ’ is processed.

Specifies a new file link name which is to replace the previous link name.

106

U3586-J-Z125-7-7600

Example:

(IN)

(OUT)

FILE SAL.FILE1,LINK=SORTIN

RDTFT

...

LINK=SORTIN

FILE=:N:$USR123.SAL.FILE1

...

CHANGE SORTIN,SORTOUT (IN)

(IN)

(OUT)

RDTFT

...

LINK=SORTOUT

FILE=:N:$USR123.SAL.FILE1

% ...

...

RELEASE SORTOUT (IN)

(01) Assigns the link name SORTIN to the file SAL.FILE1.

(02) Reads the task file table.

(03) Changes the link name SORTIN to SORTOUT.

(04) The link name SORTOUT is to be deleted.

For a further example, see the HOLD command.

CHANGE

(01)

(02)

(03)

(02)

(04)

U3586-J-Z125-7-7600

107

CONNECTION

CONNECTION Enter virtual connection in CLT

Application group: Transaction mode (DCAM) (page 33)

Command description

The CONNECTION command enables DCAM users to store or delete data concerning a virtual connection in a process-specific table known as the Communication Link Table

(CLT).

The values contained in this table supplement or replace the relevant entries in the connection control block CCB (Assembler) or in the connection structure (COBOL) while such a connection is being established. The linkage between the CLT entry and this program area is provided by the link name, which must be specified both in the command and in the program. (See also the "DCAM Program Interfaces" [6] and

"DCAM Macros" [17] manuals.)

The CONNECTION command can only affect connection setup if a link name has been defined in the program.

Format and operand description

Operation

CONNECTION

CONN

Operands

[partnername]

,LINK=linkname

[,PRONAME=procname]

[,USERFLD=userfield]

[,LOGPW=password]

108

U3586-J-Z125-7-7600

CONNECTION

partnername

LINK=linkname

Specifies the name of the communication partner with whom a connection is to be established.

The name, which may be up to 8 bytes long, must consist of

EBCDIC characters of which the first must be a letter, "@", "#", or

"$".

Specifies a link name consisting of no more than 8 EBCDIC characters, of which the first must be a letter, "@", "#", or "$".

This link name establishes the link between the entry in a processspecific table (CLT) and an area in the program (CCB or connection structure).

Special function: If LINK is the only operand in the CONNECTION command, the CLT entry associated with the specified link name is deleted.

LOGPW=password Specifies the password which the communication partner must give when he wishes to establish a connection.

The password is 4 bytes long and can be a character constant

(C’xxxx’) or hexadecimal constant (X’xxxxxxxx’).

PRONAME=procname

Specifies the name of the processor node in which the partner is located as a station.

This name consists of no more than 8 EBCDIC characters, of which the first must be a letter, "@", "#", or "$".

USERFLD=userfield

Specifies a field where you can store additional information which serves as a user-own identifier for the virtual connection.

"userfield" is 4 bytes long and can be a character constant (C’xxxx’) or hexadecimal constant (X’xxxxxxxx’).

This operand is ignored in DCAM-COBOL programs.

U3586-J-Z125-7-7600

109

CONNECTION

Example

The CONNECTION command shown below has the following effects during connection setup:

1. The name of the processor node is changed and

2. the password FR is specified.

110

Fig. CONN-1 Entering the virtual connection in the CLT

U3586-J-Z125-7-7600

COPY

COPY Copy file

Command description

The COPY command can be used to copy files, file generations or file generation groups from disk to disk from disk to tape from tape to disk.

The files are copied block-by-block; thus the command cannot be used to change the file attributes (exception: block control format, see below).

If the target file has not yet been cataloged, it is automatically created on public disk. If it is to be created on private disk or tape, it must be created with the FILE command

(DEVICE and VOLUME operands) prior to copying.

The primary and secondary allocations for a target file automatically created on public disk are taken from the source file if the latter is also on disk. If the source file is on tape, default values are used for the primary and secondary allocations.

The primary and secondary allocations for a cataloged target file on disk are only changed if the target file is smaller than the source file and the secondary allocation is

The COPY command is rejected if write access is not allowed for the target file (ACCESS=READ, EXDATE > current date, file protected by write password or BASIC-ACL); the secondary allocation is 0 and the primary allocation is too small to accommodate the file to be copied; the source file is an ISAM file on private disks with separate index and data sections.

If a file on private disk has only one entry in the system catalog but none in the F1 label, the system catalog entry will be deleted. If this file is the source file, the command will be rejected after the catalog entry has been deleted. If it is the target file, a new file will be created in public storage.

COPY operates internally with the link name DMCOPY11 for source files and

DMCOPY22 for target files.

BACL-protected PLAM libraries cannot be copied.

U3586-J-Z125-7-7600

111

COPY

Changing the block control format

In addition to the keyed file format (BLKCTRL=PAMKEY), BS2000 versions as of V10 also provide a non-keyed file format (BLKCTRL=DATA/NO). The PAMCONV utility routine is normally used to convert files from one format to the other. However, in certain cases it is also possible to use COPY to generate a target file whose block control format is different from that of the source file. In order to achieve this, the command

FILE target-file,link=dmcopy22,BLKCTRL=...

must be issued before the

COPY command. The COPY command must then contain the operand specification

BLKCTRL=IGNORE/CHECK.

Copying tape files

Source files on tape with BLKCTRO=PAMKEY must have standard block length. Target files with BLKCTRL=PAMKEY are created on tape with standard block length. (Standard block length for tape files: 16 bytes (PAM key) + 2048 bytes (PAM block)).

Tape files with BLKCTRL=DATA/NO whose BLKSIZE is a multiple of 2048 bytes can also be copied with COPY.

If NK files are copied to tape, the BLKCTRL information is lost when the catalog entry is deleted. If the file is to be copied back again, the COPY command must be preceded by a FILE command with the operands STATE=FOREIGN and LINK. The correct value for the BLKCTRL operand must be specified in the FILE command, i.e. either NO or

DATA, depending on the file format.

If a K file (BLKCTRL=PAMKEY) is inadvertently copied to an NK file

(BLKCTRL=DATA), the resulting disk file cannot be read, because the first 16 bytes of each PAM page, which contain data when BLKCTRL=PAMKEY applies, are overwritten with management information.

COPY allows only one tape to be used for source and target file (no continuation tape).

Although a number of files can be copied to one tape, it is not possible to copy files spread over a number of tapes.

Before copying a tape file that has not yet been cataloged (remote tape file), the file attributes must be defined by issuing a FILE command with the file link name valid for the COPY command:

On completion of the copying procedure, file link names DMCOPY11 and

DMCOPY22 are implicitly released. Under certain circumstances, this can cause the release of an existing TFT entry.

/FILE pathname1,LINK=DMCOPY11,STATE=FOREIGN,BLKCTRL=...

112

U3586-J-Z125-7-7600

COPY

Copying file generation groups

Only a file generation group comprising SAM file generations with the same attributes

(e.g. same record and block lengths, same record format, same BLKCTRL value) can be copied to a single file or file generation. This file generation must not belong to the file generation group to be copied.

A file generation group can only be copied to another file generation group if one of the following conditions is satisfied:

The two file generation groups have matching group entries (i.e. identical values for

GEN, FIRST, LASTGN and BASE).

The file generation group to which the copy is to be written must already contain the FIRST to LASTGN generations (i.e. the generations must be cataloged).

The GEN value is identical for both file generation groups and the generation group to which the copy is to be written still contains no generation (i.e. FIRST, LASTGN and BASE have the value zero).

Remote file access (see also "RFA" manual [12])

If a file is copied from remote system to remote system with input/output on two different systems, then this is supported by the higher-ranking execution routine. The local system serves as an intermediate station for the data transfer. The RFASTART command must be issued for both remote systems before the copying process commences.

When a remote file is copied to a local file with the SAME operand, the passwords are not included.

If NK files are to be transferred to systems with an operating system version earlier than BS2000 V10 or if a K file from a system with an operating system version earlier than BS2000 V10 must be stored on an NK disk, the COPY command must be issued in the system with BS2000 V10; the file must be converted by means of the PAMCONV utility routine before or after copying (see "Utility Routines" manual [16]).

If operands which are invalid in the remote system’s BS2000 version are specified, the entire command is rejected (BLKCTRL=CHECK/IGNORE for BS2000 < V10).

An NK file can be copied from BS2000 V10.0A to BS2000 V9.5 or an earlier version.

However, if the file has a data format which is not supported in the target system, this may cause problems.

U3586-J-Z125-7-7600

113

COPY

114

Format and operand description

Operation

COPY pathname1 catid userid filename pathname2

Operand

REPLACE pathname1,pathname2[,SAME][,WRITE= YES

NEW[,DIALOG=

]

IGNORE

[,BLKCTRL=

CHECK

] stands for: [:catid:][$userid.]filename

"pathname1" is the file/file generation/file generation group to be copied. The file/file generation/file generation group must be shareable (SHARE=YES; BASIC-ACL with access right) if it is not cataloged under the ID of the user issuing the job.

If "pathname1" is an FGG, "pathname2" must also be an FGG unless the FGG "pathname1" consists of SAM file generations with identical attributes as regards record format, record length and block size. In this case, it is possible to copy into a single file or into a file generation, provided that this file generation does not belong to the

FGG which is to be copied.

Catalog ID of the pubset on which the file is stored.

Default value: catalog ID assigned to the user ID (JOIN entry).

User ID to which the file is assigned.

Default value: User ID from the LOGON command.

Fully-qualified name of the file, file generation or file generation group which is to be copied.

stands for: [:catid:][$userid.]filename

"pathname1" and "pathname2" must not designate the same file.

"pathname2" specifies the target file.

If "pathname2" is not yet cataloged, only the user ID entered in the

LOGON command may be specified. If "pathname2" is already cataloged, write access must be permitted, i.e. any existing write password must be specified, there must be no retention period specified for the file, the access type must be ACCESS=WRITE and the file must have BASIC-ACL access rights.

U3586-J-Z125-7-7600

catid userid filename

BLKCTRL

=IGNORE

COPY

If "pathname2" is cataloged under a foreign user ID, this user ID must be specified and the file must be shareable (SHARE=YES in the catalog entry and BASIC-ACL access rights).

If "pathname2" is an FGG, "pathname1" must also be an FGG.

Catalog ID of the pubset on which the file is stored.

Default value: catalog ID assigned to the user ID (JOIN entry).

User ID to which the file is assigned.

Default value: user ID from the LOGON command.

Fully-qualified name of the copy (target file).

Specifies whether the block control attributes (or the TFT entry for the file link name DMCOPY22) of the target file and source file may differ. Default value: The target file or TFT entry must have the same block control attributes as the source file.

An inconsistency in block control attributes may be ignored in the following cases:

=CHECK

Source file

PAMKEY

DATA (for disk file only)

Target file

DATA (for disk file only)

PAMKEY

If a file with BLKCTRL=PAMKEY is copied to a file with

BLKCTRL=DATA/NO, data in the user section of the PAM key is lost.

Inconsistencies in block control attributes are to be ignored only if no user data in the user section of the PAM key would be lost in the transfer. If the user section of the PAM key contains no user information, inconsistencies in block control attributes can be ignored in the following cases:

Source file

PAMKEY

Target file

DATA (for disk files only)

U3586-J-Z125-7-7600

115

COPY

116

DIALOG

=YES

=NO

SAME

The DIALOG operand is only evaluated in interactive mode if

WRITE=NEW is specified at the same time.

If the file "pathname2" contains data, i.e. the target file is not empty, the operating system should ask if the file is to be overwritten before copying the source file. If "pathname2" is empty or is a tape file, the operating system does not ask before overwriting it. DIALOG=YES is the default setting.

If "pathname2" already exists, the COPY command is rejected;

"pathname2" is not overwritten.

The "pathname2" copy receives the same file backup and file protection attributes as "pathname1" (the values for BACKUP,

LARGE, RETPD, DESTROY, SHARE, ACCESS, MIGRATE and the same passwords). The AUDIT value, however, is not transferred. If

"pathname2" is not yet cataloged, and if SAME is not specified, the new file is created with the default attributes (see the default settings for the operands of the CATALOG command, e.g. SHARE=NO,

ACCESS=WRITE etc.).

The operand SAME is ignored if "pathname2" is cataloged under a foreign user ID or is a file generation (its file attributes are then defined in the group entry).

If a temporary file is copied into a permanent file with the operand

SAME specified, the permanent file receives the attribute

BACKUP=E, i.e. the new file is ignored for ARCHIVE save runs. If the new file is to be saved automatically using ARCHIVE, the

BACKUP value must be changed by means of a CATALOG command.

If "pathname1" is protected by a BASIC-ACL entry or an ACL entry, the following applies if SAME is specified:

If the target file is created on a private disk, it receives the same

BASIC-ACL protection attributes as the source file. If an ACL entry exists for the source file, the default protection attributes -

SHARE=NO and ACCESS=WRITE - are assigned to the target file.

If the target file is created on a magnetic tape, the default protection attributes - SHARE=YES and ACCESS=WRITE - are assigned to it, regardless of the protection attributes defined for the source file in the ACL or BASIC-ACL entry.

U3586-J-Z125-7-7600

COPY

WRITE

=REPLACE

If the source file is not cataloged under the user ID from which

COPY is invoked, the default protection attributes are assigned to the target file, regardless of the protection attributes assigned to the source file in the ACL or BASIC-ACL entry. The default protection attributes are: SHARE=NO and ACCESS=WRITE for a disk file SHARE=YES and ACCESS=WRITE for a tape file

Specifies whether an existing target file "pathname2" is to be overwritten. If "pathname2" is a tape file or is empty, the WRITE operand will be ignored and the old file "pathname2" overwritten without warning.

The file/file generation/file generation group designated by

"pathname2" is overwritten without output of a message; default value.

"pathname2" is not overwritten (see also DIALOG operand) =NEW

Examples

Example 1

: SAME operand

(IN)

(OUT)

(IN)

(OUT)

FS MAX.FILE.3

% DMS0533 REQUESTED FILE NOT CATALOGED ON PUBSET ’N’. COMMAND TERMINATED

COPY MAX.DAT,MAX.FILE.3,SAME

FS MAX.FILE.3,A

00000003 :N:$USR123.MAX.FILE.3

FCBTYPE = SAM

LASTPG = 00000001

SHARE = NO

ACL = NO

CRDATE = 1990-12-18

VSNTYPE = PUB

2ND ALLO= 00003

ACCESS = WRITE

AUDIT

EXDATE

= NONE

= 1990-12-18

DESTROY = NO

LADATE = 1990-12-18

EXPASS = NONE RDPASS = YES

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

WRPASS = NONE

VERSION = 001

BACKUP = A

BLKSIZE = 002048

RECSIZE = 000000

PUBN01 / D3480 / 001

MIGRATE = ALLOWED

BLKCTRL = PAMKEY

VSN/DEV/EXT =

EXTCNT =

:N: PUBLIC:

1 FILE RES= 3 FREE= 2 REL= 0 PAGES

U3586-J-Z125-7-7600

117

COPY

Example 2

: Copying temporary files

(IN)

(OUT)

(IN)

(OUT)

COPY MAX.FILE,#TEMP

FSTAT #TEMP,ALL

00000003 :N:$USR123.S.212.0X5S.TEMP

FCBTYPE = SAM

LASTPG = 00000001

VSNTYPE = PUB

2ND ALLO= 00003

SHARE = NO

ACL = NO

CRDATE = 1990-12-18

RDPASS = NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

VSN/DEV/EXT =

EXTCNT = 1

:N: PUBLIC: 1

BACKUP = E

BLKSIZE = 002048

RECSIZE = 000000

PUBN00 / D3480 / 001

FILE

ACCESS

AUDIT

EXDATE = 1990-12-18

WRPASS

VERSION = 001

RES=

= WRITE

= NONE

3 FREE=

COPY #TEMP,MAX.PERM.1

COPY #TEMP,MAX.PERM.2,SAME

FSTAT MAX.PERM.,ALL

00000003 :N:$USR123.MAX.PERM.1

FCBTYPE = SAM

LASTPG = 00000001

VSNTYPE = PUB

2ND ALLO= 00003

ACL

= NO

CRDATE = 1990-12-18

RDPASS = NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

VSN/DEV/EXT =

EXTCNT = 1

ACCESS

AUDIT

EXDATE

= WRITE

= NONE

= 1990-12-18

WRPASS = NONE

VERSION = 001

BACKUP = A

BLKSIZE = 002048

RECSIZE = 000000

PUBN01 / D3480 / 001

00000003 :N:$USR123.MAX.PERM.2

FCBTYPE = SAM VSNTYPE = PUB

LASTPG = 00000001

ACL

= NO

CRDATE = 1990-12-18

RDPASS = NONE

2ND ALLO= 00003

ACCESS = WRITE

AUDIT

EXDATE

WRPASS

= NONE

= 1990-12-18

= NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

VSN/DEV/EXT =

EXTCNT =

:N: PUBLIC:

VERSION = 001

BACKUP = E

BLKSIZE = 002048

RECSIZE = 000000

PUBN02 / D3480 / 001

FILES RES= 6 FREE=

DESTROY = NO

LADATE = 1990-12-18

EXPASS = NONE

MIGRATE = INHIBIT

BLKCTRL = PAMKEY

2 REL= 0 PAGES

DESTROY = NO

LADATE = 1990-12-18

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = PAMKEY

DESTROY = NO

LADATE = 1990-12-18

EXPASS = NONE

MIGRATE = INHIBIT

BLKCTRL = PAMKEY

4 REL= 0 PAGES

118

U3586-J-Z125-7-7600

COPY

Example 3

: Overwriting files with/without dialog

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

COPY MAX.FILE,MAX.FILE.3,WRITE=NEW

% DMS0518 FILE ’:W:$US123456.MAX.FILE.3’ ALREADY EXISTS. OVERWRITE ?

REPLY (Y=YES; N=NO)?

COPY MAX.FILE,MAX.FILE.3,WRITE=NEW

% DMS0518 FILE ’:W:$US123456.MAX.FILE.3’ ALREADY EXISTS. OVERWRITE ?

REPLY (Y=YES; N=NO)?

% DMS0519 COPY COMMAND WITHDRAWN BY CALLER

Example 4

: Copying files to private disk

(IN)

FILE MAX.PRIV.DAT.2,DEVICE=D3480,VOLUME=WORK01

COPY MAX.FILE,MAX.PRIV.DAT.2

(01)

(02)

(03) (IN) FSTAT MAX.PRIV.DAT.2,ALL

(OUT) 00000003*:W:$US123456.MAX.PRIV.DAT.2

FCBTYPE = SAM VSNTYPE = PVT

SHARE = NO

ACCESS# = 001

LASTPG = 0000001 2ND ALLO= 00009

ACCESS = WRITE

CRDATE = 88-11-10 EXDATE = 88-11-10 LADATE = 88-11-10

RDPASS = NONE

VERSION = 001

DESTROY = NO

BLKTYPE = STD

BLKCTRL = PAMKEY

WRPASS = NONE

LARGE

AUDIT

= NO

= NONE

BLKSIZE = 002048

EXPASS = NONE

BACKUP = A

RECFORM = (V,N)

MIGRATE = ALLOWED

RECSIZE = 00000

VSN/DEV/EXT =

EXTCNT =

:W: PRIVATE:

WORK01 / D3480

1 FILE.

RES=

/ 001

3, FREE= 2, REL= 0 PAGES

(01) The FILE command creates the catalog entry for a file, and simultaneously requests the specified private disk.

(02) The file "copy" is stored on the private disk specified in the FILE command.

(03) This is the catalog entry of the file "copy" stored on private disk. Note the fields

VSNTYPE=PVT, VSN/DEV/EXT=WORK01/D3480/001, which indicate the disk on which the file has been stored.

U3586-J-Z125-7-7600

119

CREATE-ISAM-POOL

CREATE-ISAM-POOL Create or join ISAM pool

Command description

The CREATE-ISAM-POOL command can be used to either create a new ISAM pool or to join in an existing one. An ISAM pool is identified by its name, its catalog ID, its scope, the type of buffering, and its size.

If a new ISAM pool is to be opened, the name must be explicitly specified; the scope

(task, system), size, and catalog ID are optional.

Format and operand description

Operation

CREATE-ISAM-POOL

Operands

POOL-NAME=name

*DEFAULT-PVS

[,CAT-ID=

[,SCOPE=

] catid

TASK[(WRITE-IMMEDIATE= )]

YES

HOST-SYSTEM([WRITE-IMMEDIATE=

YES

[,SIZE=

STD }

] size

] [,CREATION-MODE=

ANY

NEW

])

]

POOL-NAME

=name

Specifies the name of the ISAM pool.

Name of the ISAM pool, 1 to 8 characters in length.

The first character must be a letter or one of the special characters

#, @; the remaining characters may consist of any combination from the character set (A,...,Z,0,...,9,$,#,@).

120

U3586-J-Z125-7-7600

CREATE-ISAM-POOL

CAT-ID Specifies the PVS catalog ID of the host system where the ISAM pool exists or is to be created. Each host system is assigned a unique catalog ID. (Different catalog IDs refer to different ISAM pools.)

=*DEFAULT-PVS

The catalog ID assigned to the user ID (JOIN entry) is used; this is the default value.

=catid Catalog ID of a pubset (PVS).

SCOPE

=TASK(....)

Defines the scope (participants) of the ISAM pool.

The ISAM pool is available only to the user’s own task; default value.

WRITE-IMMEDIATE

=NO Modified blocks of a file are not immediately saved to disk unless

WROUT=YES was specified earlier in the FILE command or in the

FCB; default value.

=YES Modified blocks of the processed file are saved to disk immediately.

=HOST-SYSTEM(....)

The ISAM pool is available to all tasks.

WRITE-IMMEDIATE

=NO Modified blocks of a file are not immediately saved to disk.

=YES

The request to open the file will be rejected if, on the one hand, the operand WRITE-IMMEDIATE=NO is specified for

HOST-SYSTEM, but on the other, WROUT=YES has been entered in the TFT or the FCB of the file to be processed.

Modified blocks of the processed file are immediately saved to disk; default value.

CREATION-MODE

Specifies, for a task-wide ISAM pool, whether it is essential that a new pool be created, or whether the task may be added to any existing ISAM pool with the same pool name, catalog ID, and scope.

ANY If the named ISAM pool already exists, the task is added to this pool; otherwise, an ISAM pool of the specified size is created.

"ANY" is the default value.

NEW A new ISAM pool is to be created. This command is rejected if an

ISAM pool with the same name, catalog ID, and scope already exists on the host system.

U3586-J-Z125-7-7600

121

CREATE-ISAM-POOL

SIZE

=STD

=size

Specifies the size of the ISAM pool in PAM pages. Since pools are created in units of segments (1 Mb for XS systems, 64 Kb for others), the specified value may be internally rounded up to the next segment boundary.

If a new ISAM pool is to be created, it should be the standard size, which is defined when the system is generated. If the new pool is to added to an existing ISAM pool, the size of the existing pool is retained; default value.

Size of the ISAM pool in PAM pages:

32 size 32767 for XS systems with 31-bit addressing;

32 size 2048 for all other systems, where the maximum size of the user address space defined by the system administrator represents the upper limit.

Use of the minimum size of 32 PAM pages restricts processing to files with a maximum block size of (STD,6) (cf. the FILE command).

When an existing ISAM pool is to be joined, the SIZE specification is ignored.

122

U3586-J-Z125-7-7600

DATA

DATA Open spoolin file

Application group: Job variable functions (page 36)

Command description

The DATA command catalogs and opens a file during spoolin from floppy disk.

Records following the DATA command are entered as data records in the opened file (SPOOLIN file). This file is closed if an END command is encountered, in which case spoolin branches back to the SPOOLIN file.

A single job can contain multiple DATA commands, each of which closes the previously opened SPOOLIN file. In this case, the END commands between the DATA commands can be omitted.

The command will be rejected in interactive mode in an ENTER job.

If a spoolin operation aborts, the DATA file continues to exist. This also applies if the

LOGON command is rejected.

The first DATA command must be issued immediately after the LOGON command for the batch job.

The data records to be entered in a SPOOLIN file may also be commands. However, the LOGON or PROCEDURE command must immediately follow the DATA command.

ISAM records start with an 8-digit key field, the increment being 100; i.e. the first record has the key 00000100, the second 00000200, etc.

A file to be created on private disk must already have been cataloged before the batch job is started.

After a file has been closed, the following message appears in the printer listing for the job:

/* REMARK n RECORDS SPOOLED IN DATA FILE

U3586-J-Z125-7-7600

123

DATA

Format and operand description

Operation

DATA pathname catid userid filename

FCBTYPE

=SAM

=ISAM

Operands pathname

[,FCBTYPE=

SAM

ISAM

][,SPACE= primary

(primary,secondary)

]

[

,RECFORM=V[,STRIP=

YES

]

,RECFORM=F[,RECSIZE=reclength]

]

[:catid:][$userid.]filename

Catalog ID of the pubset on which the file is to be initialized.

Default value: the catalog ID assigned to user ID (JOIN entry).

The specified pubset must have been imported when the

DATA command is executed; otherwise, the DATA command will be rejected.

User ID of the caller; may be omitted since the user ID from the

LOGON command is the default value.

Fully-qualified file name.

The file is cataloged under this name. "filename" can also be the name of a temporary file (see the manual "DMS Introductory Guide and Command Interface" [8].

Any existing file of the same name will be overwritten.

Entering the name of a file generation or file generation group is not permitted; this also applies to the name of a file group in the case of disk files.

Specifies the access method for the file.

124

U3586-J-Z125-7-7600

DATA

SPACE

=primary

RECFORM

"primary" specifies how much storage space in the file is to be newly allocated.

=(primary,secondary)

"secondary" specifies how much storage space in the file is to be allocated automatically when additional storage space is required in the course of file processing (see also the FILE command, SPACE operand).

If the operand is omitted, "primary" and "secondary" assume the values defined at system generation time (see the "System

Installation" manual [13]).

Specifies variable-length records; i.e. every record has at its beginning the 4-byte record length field, in the first two bytes of which the record length is entered.

Specifies fixed-length records.

STRIP

=YES

=NO

Removes blanks at the end of variable-length records

(RECFORM=V).

Records containing only blanks are reduced to 1 blank.

Blanks at the end of a record are not removed.

RECSIZE

=reclength

Specifies the record length for RECFORM=F.

"reclength" is defined as follows:

For SAM files:

For ISAM files:

1 "reclength" 128

1 "reclength" 136

If the specified record length is greater than the length in the HDR1 label, the end of the entered record is filled with blanks.

If the specified record length is smaller, the record is truncated.

This operand, when omitted, always defaults to the maximum value.

U3586-J-Z125-7-7600

125

DATA

Error messages

In the event of errors, the following messages are included in the SYSLST log. A

branch is made to the next STEP command or to the LOGOFF command in each

case.

/* ERROR

SEQUENCE ERROR IN DATA FILE

Error in command sequence (see above)

FORMAT ERROR IN DATA FILE

Invalid file name (cf. fully-qualified file name)

/* ERROR

RESOURCE ERROR IN DATA FILE

No more memory space available (SPACE operand)

FILETYPE ERROR IN DATA FILE

Contradictory file attributes (cf. FCBTYPE, RECFORM and RECSIZE operands)

I/O ERROR IN DATA FILE

Error when accessing the DATA file

126

U3586-J-Z125-7-7600

DCLJV

DCLJV Define JV link name

The DCLJV command is only available with the software product JV (see also the "Job

Variables" manual [11]).

Command description

The DCLJV command is used to assign a link name to a job variable. It also creates a catalog entry if the JV did not already exist and if the user has catalog authorization

(see CATJV).

The JV link names assigned to the JV names are listed in the JV Link Table.

Only one entry may exist in the JV Link Table for each link name. However, a job variable can have more than one link name.

Format and operand description

Operation

DCLJV

Operands jvname[,LINK=*jvlink] jvname

LINK=*jvlink

Fully-qualified name of a permanent or temporary job variable. If the

JV already exists, you must have access authorization. If it is a new job variable, it is cataloged under the specified name with the default functions of the CATJV command. In this case, only the system administrator may specify a user ID other than his own.

Indicates the link name (first character "*") under which the job variable can immediately be addressed within the job. The maximum length of the link name is 8 characters, including "*".

If in a DCLJV command the same link name is specified as in a previous DCLJV command, the previous assignment is superseded by the new assignment.

For examples, refer to the "Job Variables" manual [11].

U3586-J-Z125-7-7600

127

DELETE-ISAM-POOL

DELETE-ISAM-POOL Delete ISAM pool/sever link to ISAM pool

Application group: Job variable functions (page 36)

Command description

The DELETE-ISAM-POOL command enables the user of one or more ISAM pools to clear down the connection to one or all of the pool(s). The specified ISAM pool is deleted if the caller is the last or only user of that pool. The command is rejected as long as there are pool link names for the caller.

Format and operand description

Operation

DELETE-ISAM-POOL

Operands

*ALL

POOL-NAME= name([CAT-ID=*DEFAULT-PVS/catid]

[,SCOPE=TASK/HOST-SYSTEM])

POOL-NAME

=*ALL

Indicates which connections to ISAM pool are to be cleared down.

Connections to all ISAM pools known to the task are to be cleared down.

=name(...)

CAT-ID

The connection to the specified ISAM pool is cleared down.

Specifies the catalog ID of the ISAM pool.

=*DEFAULT-PVS

The catalog ID assigned to the user ID is used (JOIN entry); default value.

=catid

SCOPE

Catalog ID of the pubset.

Indicates the scope of the command.

=TASK The command only affects local ISAM pools; default value.

=HOST-SYSTEM

The command only affects global ISAM pools.

128

U3586-J-Z125-7-7600

DELON

DELON Delete ON command

The DELON command is only available with the JV software product (see "Job

Variables" manual [11]).

Command description

The DELON command deletes one or more ON commands.

Format and operand description

Operation

DELON

Operands

.name

onid

ALL name onid

Label which identifies the ON command. If you have assigned the same label to more than one ON command, all effective ON commands identified by "name" are deleted.

ON identifier which is output to SYSOUT; identifies the ON command to be deleted. "onid" is generated during the processing of a syntactically correct ON command and is a job-related local number. Thus, in interactive mode, ON commands which have no

"name" identifier can also be deleted.

All effective ON commands defined within the user job are deleted.

ALL

For examples refer to the "Job Variables" manual [11].

U3586-J-Z125-7-7600

129

DO Initiate procedure file

Application group: Device and volume reservation (page 29)

Command description

The DO command is used to initiate a command sequence stored in a file (procedure file).

The procedure file is opened and the command sequence is executed. During execution, the symbolic operands contained in the command sequence are replaced by the current operand values specified in the command call. This operation is referred to as a DO procedure.

Procedure files are SAM or ISAM files with variable-length records (RECFORM=V). A procedure file is stored: as a cataloged (also temporary) file as a J-type member in a program library (LMS library routine)

The first data record in a procedure file is the PROCEDURE command. Subsequent records are commands or data. The last record is the ENDP command (see Figs. DO-1 and DO-2 on the next page).

When the DO command is issued, the procedure file is assigned to the (system) file

SYSCMD. If data is also to be read from the procedure file, the system files SYSDTA and SYSCMD in the procedure file must be equated.

[Command: /SYSFILE SYSDTA=(SYSCMD)].

Command procedures can be nested as often as required.

Nesting means:

Processing of procedure file commands is interrupted by a call to another procedure file. Once the ENDP command has been reached, the remaining commands in the most recently exited procedure file are read, etc.

DO procedures only result in "pseudo-nesting" (see Fig. DO-2), however, since once the

ENDP command has been reached, the command following the first DO command is read. Genuine nesting can only be achieved by means of CALL procedures.

130

U3586-J-Z125-7-7600

Fig. DO-1 DO procedure

Fig. DO-2 Nesting of DO procedures (pseudo nesting)

U3586-J-Z125-7-7600

131

Format

Operation

Operands pathname[, sympar=[paramvalue]

[sympar=]paramvalue

,...]

Operand descriptions see CALL command.

132

U3586-J-Z125-7-7600

DROP

DROP Cancel HOLD status

The DROP command is used to cancel the HOLD status imposed by the HOLD command on an entry in the task file table (TFT). If a RELEASE command is still pending for this entry, it will now be processed.

Format and operand description

Operation

DROP

Operands

[link] link Specifies the file link name, i.e. the name of the task file table entry for which the HOLD status is cancelled.

If this entry is omitted, the first TFT entry with the file link name

C’ ’ is processed.

For examples, see the HOLD command.

U3586-J-Z125-7-7600

133

END

END Close spoolin file

Application group: Job variable functions (page 36)

Command description

The END command closes a file that was cataloged and opened by a DATA command.

The command refers to job input from the batch terminal or from floppy disk and is processed during spoolin of the batch job.

An END command preceding a DATA command may be omitted since previously opened SPOOLIN files are automatically closed when a new DATA command is processed.

Format

Operation

END

Operands

134

U3586-J-Z125-7-7600

ENDON

ENDON Terminate ON statement sequence

The ENDON command is only available with the software product JV (see also the "Job

Variables" manual [11]).

Command description

The ENDON command is used to terminate an ON or TIMEOUT statement sequence.

If no corresponding ON command can be found for an ENDON command (the command sequence contains only ENDON), then an appropriate SYSOUT message is output and processing continues with the next command.

If the ENDON command is missing from an ON/ENDON construct, the job will terminate abnormally in batch mode. In interactive mode, the procedure is terminated.

Format

Operation

ENDON

Operands

Examples can be found in the "Job Variables" manual [11].

U3586-J-Z125-7-7600

135

ENDP

ENDP Terminate procedure file

Command description

The ENDP command is used to terminate a procedure. If the procedure was called with a DO command, ENDP moves the SYSCMD system file to the primary command input

(terminal in interactive mode; SPOOLIN or ENTER file in batch mode), or to the last procedure level exited with CALL. If the procedure was called with the CALL command,

SYSCMD returns to the calling procedure (see Fig. ENDP-1).

Following the ENDP command, the SYSDTA, SYSIPT, SYSLST, SYSOPT, SYSOUT and

TASKLIB assignments are restored as they were before the procedure level was called.

Any file assigned in the procedure by SYSFILE SYSLST=... will be closed when ENDP is issued.

If the ENDP command is issued in ESCAPE mode, SYSCMD returns to the previous procedure level (cf. RTI command: procedure execution is resumed from the point it was interrupted with ESCAPE).

If ENDP and DO commands are specified in ESCAPE mode, SYSCMD will be returned to the preceding procedure level, unless SYSCMD is already at primary command input level (level 0).

After the ENDP command or execution of the DO procedure, a message is output with the updated level number of the nested procedure.

Exception:

No message is issued when the primary command input level has been reached.

136

U3586-J-Z125-7-7600

ENDP

Fig. ENDP-1 Combination of DO and CALL procedures

The arrows show the route of the system file SYSCMD, i.e. command input.

Format

Operation

ENDP

Operands

For examples see the PROCEDURE, ESCAPE and RTI commands.

U3586-J-Z125-7-7600

137

ENTER

ENTER Process ENTER job

7) which is printed in uppercase letters (including user ID and

Command description

The ENTER command is used to transfer a batch job stored in an (ENTER) file to the operating system for processing.

The (ENTER) file is a cataloged file or a library member. The ENTER command can be issued in both command mode and program mode (see also "Executive Macros" manual [5]).

The new job is given its own task sequence number (TSN) and is executed in a separate task, regardless of which task called it. The specifications in the ENTER command indicate the (ENTER) file, identify the caller (access authorization and accounting) and characterize the job and the logging mode governing the job run.

The specifications regarding access authorization are checked against the entry in the

JOIN file, additional specifications regarding job class and job attributes (job and run priority, system resources) are also checked against the entry in the job class definition.

You can access these entries by means of the SHOW-USER-ATTRIBUTES or SHOW-

JOB-CLASS command.

If the entries for PRIORITY and NTL (No Time Limit) in the JOIN file and the job class definition are not the same, the value which is most advantageous to you will be accepted.

The job runtime log is output to the SYSOUT (system) file. In addition, it may be specified that the log should also be written to SYSLST.

An (ENTER) file always begins with the LOGON command and ends with the LOGOFF command. The operands in the LOGON command are not evaluated, unless the

(ENTER) file was started at the console. A command call error in an ENTER file usually triggers the SPIN-OFF mechanism (branch to the next ABEND, ABORT, STEP or

LOGOFF command).

A copy of the file to be initiated is created under the name S.IN

if the ENTER file is on private disk, if the ENTER file is cataloged under another user ID, if the ENTER file is a temporary file, or if the ENTER file is a library member.

After the ENTER file has been copied, the library member can be modified again. For this reason, the file at the time of ENTER may be different from the current one.

The S.IN file is automatically deleted at job end (LOGOFF) unless checkpoints were set during job execution (WRCPT macro, see "Executive Macros" manual [5]), in which case the S.IN.tsn file is required to ensure trouble-free restart (RESTART command)

138

U3586-J-Z125-7-7600

ENTER

Although S.IN... files are password-protected (EXPASS), it is possible to erase them with an /ERASE command without previously specifying the password. This makes it possible to remove from the system S.IN... files which are no longer needed or which were not deleted by the system itself.

ENTER files can be password-protected (CATALOG command) against reading

(RDPASS), writing (WRPASS) and execution (EXPASS). The EXPASS password or a higher-ranking password must be specified in a PASSWORD command before specifying an ENTER command. If the file is to be deleted after execution (ENTER...,

ERASE=YES), the WRPASS password must also be specified.

Passwords are checked during processing of the ENTER command. If a user subsequently changes the passwords, the access right still applies and the file is executed.

ENTER files may be SAM or ISAM files with variable record length (RECFORM=V). 72 characters are interpreted per data record. In the case of ISAM files, the key field may be located anywhere in the record because it is masked out.

The PRIORITY and MSG operands are still supported for reasons of compatibility only.

Instead, you should use RUN-PRIO or RUN-PRIO in conjunction with

START=IMMEDIATELY (for PRIORITY=(p,EXPRESS)) and LOG.

Fig. ENTER-1 Initiating an ENTER job

U3586-J-Z125-7-7600

139

ENTER

The following table contrasts the characteristics of ENTER and procedure files.

How is the file or command sequence in the file called?

Is a new job created when the file is called?

ENTER file

With the

ENTER command

Yes, a batch job

Which commands delimit the files?

Can the file also be called within an ENTER file or a procedure file?

What happens when the file is called from a terminal?

LOGON command

LOGOFF command

Yes

The task sequence number (TSN) for the new batch job is displayed on the terminal. This job is then continued separately from the interactive job which has generated it.

Procedure file

With the DO or CALL command

No: the DO or CALL command merely converts the procedure file to system file SYSCMD.

PROCEDURE command

ENDP command

Yes

The initiated procedure is part of the calling interactive job currently executing on the terminal. When all the commands in the procedure file have been processed, commands may be entered from the terminal again.

Yes Can symbolic operands whose values are defined only when the file is called or executed be used in the file?

140

U3586-J-Z125-7-7600

ENTER

Format and operand description

Name Operation

[.jobname] ENTER

Operands pathname

[,userid1,accountno[,password]]

[,FPASS=password]

[,ERASE=

YES

]

[,HOST=

’hostid’ jvname1

][,CAT=

’catid’ jvname2

]

[,JOB-CLASS= jobclass

*STD

]

[,MONJV=jvname][,JVPASS=password]

[,JOB-PRIO= jprio

]

STD

[,RERUN=

YES

]

[,FLUSH=

YES

]

[,START=

STD

SOON

IMMEDIATELY

HOURS=hour[,MINUTES=minute]

WITHIN(

[HOURS=hour,]MINUTES=minute ) ]

AT([DATE=yy-mm-dd,]TIME=hh:mm)

EARLIEST([DATE=yy-mm-dd,]TIME=hh:mm)

LATEST([DATE=yy-mm-dd,]TIME=hh:mm)

AT-STREAM-STARTUP

U3586-J-Z125-7-7600

141

ENTER

Name Operation

ENTER

(cont.)

Operands

[,REPEAT=

STD

DAILY

WEEKLY

HOURS=hour[,MINUTES=minute]

PERIOD(

[HOURS=hour,]MINUTES=minute

AT-STREAM-STARTUP

)

[,RUN-PRIO= rprio

]

STD t

[,TIME= NTL ]

STD number

[,PRINT= NO

STD

] number

[,PUNCH= NO

STD

]

[,LOG=(LISTING=

YES

)]

*NO

[,JOB-PAR= string

] p

[,PRIORITY=

([p],EXPRESS)

]

[,MSG=[

][L][H]]

142

U3586-J-Z125-7-7600

jobname pathname catid userid filename library

(member)

U3586-J-Z125-7-7600

ENTER

Defines a 1- to 8-character job name (for valid characters see page

account number) in job listings and on any spool jobs initiated by the job.

"jvname" is also the label used for branching to the command.

filename stands for: [:catid:][$userid.] library(member)

Catalog ID of the pubset on which the file is stored. Default value: the catalog ID assigned to the user ID (JOIN entry).

User ID to which the file is assigned.

Default value: the user ID from the LOGON command.

Name of the cataloged file with the batch job.

If the file is not cataloged under your user ID, it must be shareable and the user ID under which it is cataloged must be specified.

The (ENTER) file must also be shareable if the task calling the

ENTER command is running under a user ID other than the one specified in the ENTER command. In this case, "password" must be specified if "userid1" is password-protected. An execute password

(EXPASS) on the file must be specified with the FPASS operand or beforehand with the PASSWORD command.

"filename" may also be the name of a temporary file (see the manual

"DMS Introductory Guide and Command Interface" [8].

File generations or file generation groups are not allowed.

Specification of a file group ("file(group)") is only allowed for tape files.

Name of an LMS library on disk (see the "LMS" manual [14]).

Name of the library member with the batch job. "member" may be up to 38 characters in length: letters special characters digits

A, ..., Z

$, #, -, ., @

0, ..., 9

The first character must be a letter. The last character must not be a hyphen.

The expression "library(member)" may be up to 42 characters in length minus the length of the catalog ID (including parentheses).

"library" or "member" may be up to 38 characters in length.

143

ENTER

userid1 accountno password

CAT

=’catid’

=jvname2

User ID for the ENTER job to be initiated.

Account number for the ENTER job.

LOGON password for "userid1".

The password cannot be logged to SYSOUT, i.e. it does not appear in the printer listing for the ENTER job.

"userid" and "accountno" may only be specified or omitted together in the ENTER command.

A status check (STATUS command) is only possible under the user

ID of the calling job.

If "userid1", "accountno" and "password" are omitted, they will be copied from the LOGON command of the initiating job.

Specifies a catalog ID. The job is directed to the computer to which the specified catalog is assigned. If both HOST and CAT are specified, the HOST operand is used to determine the host computer.

Catalog ID. "catid" must be a catalog which is known to and accessible in the multiprocessor network, otherwise the ENTER command will be rejected.

Job variable containing "catid". "jvname2" must contain the "catid" of a catalog which is known and accessible in the multiprocessor network, otherwise the ENTER command will be rejected. If

"jvname1" or "jvname2" is not accessible, the ENTER command is rejected. The syntax for "jvname1"/"jvname2" must be in accordance with the conventions for a GETJV operation.

HOST and CAT are only available with the software products

MSCF and JV.

144

U3586-J-Z125-7-7600

ERASE

=NO

=YES

FLUSH

=YES

=NO

ENTER

Specifies that the ENTER file should not be erased at the end of the job (default value).

Specifies that the ENTER file should be erased at the end of the

ENTER job.

ERASE=YES will be ignored if a) the file is a library member, b) the file is not cataloged under the caller’s user ID, c) the job is terminated abnormally, d) the job is aborted by the ABEND, CANCEL or

SHUTDOWN command.

c) and d) do not apply if: the file is on private disk, the file is a temporary file, the file is cataloged under the caller’s user ID and the

ENTER job is to be executed under another user ID.

In such cases the file is erased after creation of the S.IN file.

The job will be removed from the job queue if it has not been processed by the end of the BS2000 session (SHUTDOWN).

The RERUN and FLUSH operands are not analyzed for a repeat job. The job is initiated at the next repetition point.

The job will remain in the job queue. The next session must be initiated with a warm start or selective start (default value).

Job control with RERUN/FLUSH

If FLUSH=YES and RERUN=YES were specified and the job was interrupted in a previous session, then FLUSH=NO will be used in the next session. This ensures that the job remains in the job queue, even if it is not initiated in this session.

A monitoring job variable is set to "$S" when the job is repeated.

RERUN and FLUSH are not analyzed for repeat jobs.

U3586-J-Z125-7-7600

145

ENTER

146

FPASS=password

Indicates the execute or write password for the ENTER file:

A write password is only needed if ERASE=YES is specified. The password (see CATALOG command: "passwords" for syntax) for the

ENTER file must be specified in the ENTER command if job distribution is requested (see "MSCF Multiprocessor System" manual

[15]). In the absence of job distribution, the password can also be specified by means of a separate PASSWORD command.

HOST

="hostid"

=jvname1

Indicates the host computer on which the job is to be executed.

"hostid" must refer to an active computer within the multiprocessor network, otherwise the ENTER command will be rejected. If both

HOST and CAT are specified, the HOST operand is used to determine the host computer.

Job variable containing "hostid". "jvname1" must contain the host ID of an active computer within the multiprocessor network, otherwise the ENTER command will be rejected.

The syntax for "jvname1"/"jvname2" must be in accordance with the conventions for a GETJV operation.

HOST and CAT are only available with the "MSCF" and "JV" software products.

JOB-CLASS

=jobclass

=*STD

Denotes a job class into which the job is to be incorporated.

Authorization for the various job classes can be displayed by means of the SHOW-USER-ATTRIBUTES or SHOW-JOB-CLASS commands.

Name of job class.

(Default) job class preset by the user or the operating system; default value

JOB-PAR

=*NO

="string"

Enables specification of additional attributes for the selected job class, provided the system administrator has defined and announced such attributes.

No additional attributes; default value.

Any sequence of characters; it is provided by the system administrator for identifying additional job class attributes.

U3586-J-Z125-7-7600

ENTER

JOB-PRIO

=jprio

=STD

JVPASS

=password

LOG=(...)

Denotes the password for access to the monitoring job variable, in accordance with the password hierarchy. The password must be specified in the ENTER command if job distribution (see "MSCF

Multiprocessor System" manual [15]) is requested. In the absence of job distribution, the password can also be specified via a separate

PASSWORD command.

JVPASS is ignored if MONJV was not specified.

Password for the "jvname" job variable.

Specifies whether or not the job runtime log will also be output to

SYSLST.

LISTING=YES The log will also be output to SYSLST.

LISTING=NO

The log will not be output to SYSLST; default value.

MONJV

Determines the priority (in relation to other jobs) for initiation of a batch job. This specification does not affect subsequent execution of the job.

Job priority. MAXIMUM jprio 9.

The lower the value, the higher (greater) the priority (urgency). The

MAXIMUM value is defined in the job class definition and can be displayed on the screen by means of the SHOW-JOB-CLASS command. If MAXIMUM=NO or no value is specified, the default priority is assumed.

The default value for the job class is used; default

Indicates a job variable that is to monitor the job.

The user can address his job via this job variable. During job execution, the operating system assigns the following values to the job variable:

$S (job in job queue),

$R (job being processed),

$T (job terminated normally) or

$A (job aborted).

When ENTER is executed, the status display for "jvname" is set to

"$S", the "tsn" display is set to the task number (TSN) for the job, and the processor display is set to the catalog ID of the processor on which the job is to be executed.

U3586-J-Z125-7-7600

147

ENTER

=jvname

MSG

If "jvname" is not accessible at command execution time, an error message is output to SYSOUT and command execution is continued without monitoring.

Both the user ID issuing the monitoring job variable and the user ID for which the job is being processed must be able to access

"jvname".

Access to the monitoring job variable is subject to the same conventions as access to the ENTER file.

The MONJV operand is only available with the JV software product (see also "Job Variables" manual [11]).

Name of job variable.

Defines the type of logging for the remainder of job execution.

Operand MSG is supported for reasons of compatibility only. MSG is completely ignored if LOG has been specified.

System messages are output in full-length form to the system file

SYSOUT (F stands for "full message"); default value.

The coded short form of system messages is output to SYSOUT (C stands for "code").

Console messages and operator responses are logged to SYSOUT for this job.

Operator commands used for controlling job execution (e.g. changes in priority) as well as general (system) warnings and error messages for the operator are not output (L stands for "log").

If the user enters MSG=LH, the messages logged to SYSLST will additionally be given the time of day at which they were issued.

All messages written to SYSOUT are also written to SYSLST (H stands for "hold message"). Exception: system messages which require a response from the user, as well as the message

ABNORMAL PROGRAM TERMINATION.

In line mode (MODE=LINE), logging takes place line by line, i.e. control character NL is analyzed. In format mode

(MODE=FORM), logging is continuous, i.e. the log is not represented true to format and control character NL is not analyzed.

148

U3586-J-Z125-7-7600

ENTER

=number

=NO

=STD

Indicates the maximum number of records which a task can output

(in summary form) to the system files SYSLST, SYSLST01,

SYSLST02 through SYSLST99. Records written simultaneously to the system files SYSOUT and SYSLST (LOG=LISTING or MSG=FH operands) are not included.

Notes on exceeding the specified number:

in batch mode the task terminates abnormally; in interactive mode, the user may specify whether the task should continue or be terminated. If continued, it will again be output until "number" is reached.

Number of records, where 0 number 999999.

Number of records is unlimited.

Default value of the selected job class; preset value.

PRIORITY Determines the priority (relative to other tasks) for executing the job.

PRIORITY is ignored if the RUN-PRIO operand has been executed.

PRIORITY is only supported for reasons of compatibility. You should use RUN-PRIO instead.

Run priority. MAXIMUM p 255.

=(p,EXPRESS) EXPRESS causes the ENTER job to be started immediately. It has no further effect on job execution.

EXPRESS is ignored if the START operand has been specified.

PUNCH

=number

=NO

=STD

Indicates the maximum number of records output by the task to the system file SYSOPT.

Number of records, where 0 number 999999.

Number of records is unlimited.

Default value of the selected job class; preset value.

Refer to the PRINT operand for information on exceeding the specified number of records.

REPEAT Indicates an interval of time after which the job is to be periodically started. The repetition is considered as a job sequence. J(0) indicates the first job run, J(1) the first repetition, ..., J(n) the nth repetition of the job. With the start of job J(i), the repetition J(i+1) is also created, where i 0.

U3586-J-Z125-7-7600

149

ENTER

=STD

=NO

=DAILY

=WEEKLY

Default value of the selected job class; preset value.

The job will not be repeated.

Daily repetition at the time-of-day specified with START.

Weekly repetition at the time-of-day specified with START.

=PERIOD(...)

Repetition following the specified interval of time (in hours and minutes).

0 hour 23; 0 minute 59.

=AT-STREAM-STARTUP

Repetition following job scheduling startup.

Specification of the repeat values (NO, DAILY, WEEKLY,

PERIOD and AT-STREAM-STARTUP) is permitted only if they are also permitted in the job class definition (see also SHOW-

JOB-CLASS command).

RERUN

=YES

=NO

RUN-PRIO

=rprio

=STD

The job will be reinitiated in the next BS2000 session if execution was interrupted by an unrecoverable system error or the end of the session.

The operands RERUN and FLUSH are not analyzed in the case of a repeat job. The job is started at the time of the next repeat.

The job will not be reinitiated.

Indicates the urgency (relative to other tasks) for processing the job.

Run priority, where MAXIMUM rprio 255.

The lower the value, the higher (greater) the priority (urgency). The

MAXIMUM value is defined both in the job class definition and in the

JOIN file, and can be interrogated by means of the SHOW-JOB-

CLASS or SHOW-USER-ATTRIBUTES command. If the values do not match, the limit value most favorable to the job is used.

Default value of the selected job class; preset value.

The default value is also used when illegal values are specified for "rprio".

150

U3586-J-Z125-7-7600

ENTER

START

=STD

=SOON

Specifies a time (period) for starting a job.

Values entered for start time:

DATE = yy-mm-dd : (yy=year, mm=month, dd=day).

TIME = hh:mm : time-of-day (hh=hour, mm=minute).

Hyphens or the colon must be included in the entry for DATE or

TIME.

Example: 31st May 1990 at 15.08 hours

AT (DATE=90-05-31, TIME= 15:08).

For TIME: 00 hh 23; 00 mm 59.

The ENTER command is rejected if the month or time-of-day specified is in the past. However, specification of a past year "yy" is interpreted as the year 20yy.

The default values SOON, IMMEDIATELY, WITHIN, AT,

EARLIEST, LATEST and AT-STREAM-STARTUP may only be specified if they are also permitted in the job class definition;

(see also SHOW-JOB-CLASS command).

The default value for the selected job class is used; preset value.

The job is to be started as soon as possible, taking its priority into account.

=IMMEDIATELY The job is to be started immediately.

=WITHIN(...) The job is to be started within the specified time (in hours and minutes).

0 hour 23; 0 minute 59.

=AT(...) The job is to be started at exactly the time (date, time-of-day) specified.

=EARLIEST(...)

The job is to be started on or after the specified time (date, time-ofday).

=LATEST(...) The job is to be started on or before the specified time (date, timeof-day).

=AT-STREAM-STARTUP

The job is to start following job scheduler startup.

U3586-J-Z125-7-7600

151

ENTER

TIME

=NTL

=STD

Denotes the maximum CPU time (in seconds) permitted for the job.

The maximum CPU time which can be specified here is determined by the job class selected.

CPU time in seconds, where 0 t maximum CPU time.

NTL: No Time Limit. The task will run with unlimited CPU time.

Default value of selected job class; preset value.

Combinations of the START and REPEAT operands:

START

IMMEDIATELY or SOON

AT or

EARLIEST

LATEST or

WITHIN

AT-STREAM-

STARTUP

AT-STREAM-STARTUP

REPEAT

DAILY or WEEKLY a) a) a) b) c) d) c) e)

PERIOD c) f) g) h) a) The first and all subsequent job starts occur as specified.

b) The first job start occurs with START=AT-STREAM-STARTUP.

All subsequent starts occur after job scheduler startup with

START=SOON.

c) Time base for the repeat cycle is the time the job was accepted.

d) The specified time (START=...., TIME=....) is the time base for the repeat cycle.

e) The first job start occurs after the job scheduler startup. This start time is the time base for the repeat cycle. The subsequent starts are effected with START=SOON.

f) The specified time (START=...., TIME=....) is the time base for the repeat cycle. The second and all subsequent starts occur with START=SOON.

g) The time base for the repeat cycle is the time the job was accepted. All subsequent starts occur with START=SOON.

152

U3586-J-Z125-7-7600

ENTER

h) Time base for the repeat cycle is the first start time. The first job start occurs after the job scheduler startup. The subsequent starts occur with START=SOON.

The nth repetition (n 1) of a job only starts when the (n-1)th has finished.

Aborting the currently running job J(n) has no effect on the start of J(n+1), where n 0.

Aborting the entire job: Both the currently running job J(n) and the subsequent job J(n+1) are terminated where n 0 (CANCEL command or make job J(n) the last one in the repeat sequence with command

MODIFY-JOB tsn,REPEAT=NO).

Examples

Example 1

File X.ENTER.1 contains the following:

/LOGON

/FSTATUS

/FSTAT ,ALL

...

/LOGOFF

The following listing is produced in interactive mode:

.........

(IN) FSTAT X.ENTER.1

(OUT) 0000003 :N:$PA123456.X.ENTER.1

:N: PUBLIC: 1 FILE.

RES=

(IN)

(OUT)

(IN)

(OUT)

ENTER X.ENTER.1,TIME=155

9 230 0.0

3, FREE=

CPU-USED CPU-MAX ACCOUNT#

155 M1234MON

2, REL=

(01)

% JMS0066 JOB ’SALEM’ ACCEPTED ON 90-12-18 AT 09:32, TSN = 0YAY.

STA T=0YAY,DISP=L

NAME TSN TYPE

SALEM 0YAY 1 WT

PRI

0 PAGES

(01) The ENTER command for file X.ENTER.1 initiates a new batch job (TSN=0YAY).

The STATUS command is subsequently used to provide information on the job status.

U3586-J-Z125-7-7600

153

ENTER

Example 2:

Specifying the TIME operand for ENTER jobs

/LOGON PA123456,M1234MON,TIME=50

(IN)

(OUT)

ENTER X.ENTER.1

(01)

% JMS0066 JOB ’SALEM’ ACCEPTED ON 90-12-18 AT 09:46, TSN = 0YDB.

(IN)

(OUT)

STA L

NAME

SALEM

TSN TYPE

0YDB 1 WT

PRI

9 230

0YCZ 3 DIALOG 0 210

CPU-USED CPU-MAX ACCOUNT#

0.0

2000 M1234MON

0.4135

% SPS0171 NO LOCAL SPOOLOUT JOB PRESENT

50 M1234MON

% SRO0376 NO RSO JOB OF TYPE=7 PRESENT

(IN)

(OUT)

(IN)

(OUT)

ENTER X.ENTER.1,TIME=60 (02)

% JMS0066 JOB ’SALEM’ ACCEPTED ON 90-12-18 AT 09:47, TSN = 0YDF.

STA L

NAME

SALEM

TSN TYPE

0YDB 1 WT

0YDF 1 WT

0YCZ 3 DIALOG

PRI

9 230

0 210

CPU-USED CPU-MAX ACCOUNT#

0.0

0.7447

% SPS0171 NO LOCAL SPOOLOUT JOB PRESENT

% SRO0376 NO RSO JOB OF TYPE=7 PRESENT

2000 M1234MON

60 M1234MON

50 M1234MON

/LOGOFF BUT

...

/LOGON PA123456,M1234MON

(IN)

(OUT)

ENTER X.ENTER.1

(03)

% JMS0066 JOB ’SALEM’ ACCEPTED ON 90-12-18 AT 10:00, TSN = 0Z19.

(IN)

(OUT)

STA L

NAME

SALEM

TSN TYPE

0YDB 1 WT

0Z19 1 WT

0Z11 3 DIALOG

PRI

9 230

0 210

CPU-USED CPU-MAX ACCOUNT#

0.0

0.4053

% SPS0171 NO LOCAL SPOOLOUT JOB PRESENT

% SRO0376 NO RSO JOB OF TYPE=7 PRESENT

2000 M1234MON

32766 M1234MON

(01) If the TIME operand is omitted from the ENTER command, the ENTER job will be given the default value from the assigned job class.

154

U3586-J-Z125-7-7600

ENTER

(02) The TIME specification in the ENTER command was assumed for the ENTER job with TSN 0YDF.

(03) A new interactive job begins. The ENTER job with TSN 0Z19 receives the default value from the assigned job class as TIME specification, as does the new interactive job.

The ENTER job with TSN 0YDF is no longer in the system.

For further examples, see the LOGON and SKIPUS commands.

U3586-J-Z125-7-7600

155

EOF

EOF Indicate end-of-file for SYSDTA

Application group: Job variable functions (page 36)

Command description

The EOF command generates an EOF condition for the system input file SYSDTA. It is used in conjunction with an RDATA macro (see the "Executive Macros" manual [5]) and a corresponding language statement in the user program. This macro reads a data record from the system file SYSDTA. If the record read is an EOF command, control is passed to the routine for end-of-file processing in the user program; otherwise, the program continues with the command following the RDATA macro. The address of this routine must have been specified as an operand in the RDATA macro.

The EOF condition is removed if the /SYSFILE SYSDTA = ... command is entered, or if the program terminates abnormally.

In interactive mode, the EOF command can be used in conjunction with the ESCAPE function to terminate data readin at the terminal (WRTRD macro, see the "Executive

Macros" manual [5]).

Format

Operation

EOF

Operands

156

U3586-J-Z125-7-7600

EOF

Examples:

Example 1:

The following command/data sequence is entered for a batch job:

/LOGON ...

/EXEC X.PROCESS

RECORD1

RECORD2

.....

Data for program X.PROCESS

(01)

/EOF

/LOGOFF

(02)

(01) Program X.PROCESS reads in data from the SYSDTA system file with the aid of the RDATA macro (see chapter 1). Since SYSDTA and SYSCMD are merged in the batch job, the data is expected immediately after the EXEC command.

(02) As soon as the EOF command is encountered, program X.PROCESS branches to its end-of-file processing routine.

Example 2:

If the data for program X.PROCESS (see Example 1) is to be entered on the terminal, the listing is as follows:

(IN) /EXEC X.PROCESS

(OUT) % BLS0500 PROGRAM PROCESS VERSION

.RECORD1

.RECORD2

.......

OF 85-08-16 LOADED

(IN) /EOF

(01) System mode is entered by means of the ESCAPE function (e.g. K2 key at the terminal), causing the system to display a slash.

(01)

(02)

(02) The EOF command indicates end-of-data for the input file. The program branches to the end-of-file routine specified in the RDATA call.

U3586-J-Z125-7-7600

157

ERAJV

ERAJV Delete job variable

The ERAJV command is only available with the JV software product (see also "Job

Variables" manual [11]).

Command description

The ERAJV command erases one or more job variables in the file catalog or overwrites the job variable values with X’00...00’. The job variable names may be specified in partially qualified form or contain wildcards.

Job-monitoring job variables are protected by the system and may not be deleted.

Format and operand description

Operation

ERAJV pathname catid

Operands

STD pathname NO

*jvlink [,CHECK= MULTIPLE

PVS

SINGLE

[,DATA=

YES

NONE

][,IGNORE= protect1

(protect1,...4)

]

NONE

[,PASSWORD= password1

(password1,...3)

]

[,LIST=

YES

]

NO stands for: [:catid:][$userid.][jvname]

"pathname" is the job variable to be erased. You can erase your own job variables only. Wildcards may be specified for "catid",

"userid" and "jvname" (cf. the FSTATUS command).

Catalog ID of the pubset containing the job variable. Default value: the catalog ID (JOIN entry) assigned to the user ID.

158

U3586-J-Z125-7-7600

ERAJV

userid jvname

*jvlink

CHECK

=STD

=NO

=MULTIPLE

=PVS

=SINGLE

User ID. Only the user ID of the current job may be specified.

Default value: user ID from the LOGON command. Specification of the user ID is mandatory if a blank is specified for "jvname".

Name of the job variable to be erased. It can be specified in fully or partially qualified form or using wildcards. The names of temporary job variables must start with a prefix.

Specifies the job variable to be erased via its JV link name.

Wildcards are not allowed for "*jvlink".

Erases all temporary job variables of the job. "#" stands for the special character defined using the system parameter TEMPFILE for identifying temporary files and job variables.

Erasing the job variable is made subject to the user’s response to a query. This operand is ignored in batch mode.

Is the default value for interactive applications or for procedures and in batch mode. The following applies:

MULTIPLE for interactive mode,

NO for procedures and batch mode.

The catalog entry or the job variable value is erased without an acknowledgment. This is the default value for batch mode and procedures.

Results in a global query for each user ID (message: JVS0465), but only if more than one job variable is to be erased. MULTIPLE is the default value in interactive mode.

Results in a global query for each pubset (message: JVS0468), but only if more than one job variable is to be erased.

A query is made for each job variable that is to be erased

(message: JVS0469).

With MULTIPLE, PVS and SINGLE, the following query is appended to each message:

REPLY (Y=YES; N=NO; T=TERMINATE; [,CHECK=NEW MODE])

U3586-J-Z125-7-7600

159

ERAJV

Response

T any other response

CHECK=

CHECK=new mode

CHECK=old mode

Effect

The erase request indicated is executed.

The erase request indicated is not executed (message JVS046A).

The erase procedure is aborted at the erase request indicated.

Same effect as N.

The current check mode is not modified.

The new check mode (SINGLE / MULTIPLE /

PVS / STD / NO takes effect immediately; response Y/N is not analyzed and can therefore be omitted.

Response Y/N is analyzed; this is also true for old mode = MULTIPLE and new mode = STD.

DATA

=NO

=YES

IGNORE

=NONE

=protect1,..4

Determines whether the catalog entry is to be erased or the job variable value is merely to be overwritten with X’00...00’.

The catalog entry is to be erased; default value.

The job variable value is to be overwritten with X’00...00’; the catalog entry is not erased.

Specifies whether protection attributes entered in the catalog for the job variable are to be ignored when the catalog entry is erased.

Protection attributes are not ignored; default value.

Specifies the protection attribute to be ignored.

The following values can be specified individually or in a list of up to four values:

ACCESS: The protection attribute ACCESS=READ and the access rights assigned with BASIC-ACL are ignored.

EXDATE: An expiration date later than the date of the current day is ignored.

160

U3586-J-Z125-7-7600

ERAJV

LIST

=NO

=YES

PASSWORD

Specifies whether the job variables erased are to be logged.

Logging is suppressed; default value.

All job variables erased without error are logged.

Enables the user to erase password-protected job variables.

Passwords specified here are not entered in the task password table.

=NONE Prevents password-protected job variables from being erased; default value.

password1,... Indicates the password(s) to be ignored when job variables are erased. Up to three passwords can be specified in a list.

Refer to "Job Variables" manual [11] for examples.

U3586-J-Z125-7-7600

161

ERASE

ERASE Erase file

Command description

The ERASE command enables you to erase files, file generation groups, file generations, temporary files and system files for output

The file to be deleted must be cataloged under your user ID.

The following types of deletion are possible: a) Logical deletion of a file ("pathname" operand):

The catalog entry is deleted and the allocated storage space released. Data bytes are not overwritten with X’00’. Example: /ERASE file b) Physical deletion of a file (DESTROY operand):

The catalog entry is deleted and the allocated storage space released. The data bytes are overwritten with X’00’. Example: /ERASE file,DESTROY

A file is also physically deleted although the DESTROY operand is omitted if

DESTROY=YES has been specified in its catalog entry (see the CATALOG command).

c) Logical deletion of the data of a file (DATA/SPACE operand):

The user is no longer able to access the contents of a file. The data bytes are not overwritten with X’00’. The catalog entry is retained. When the DATA operand is specified, the storage space remains allocated; when SPACE is specified, the storage space is released. Example: /ERASE file,DATA d) System files for output (SYSLST/SYSLSTn/SYSOUT/SYSOPT operands):

Only the contents of the file are logically deleted, while the catalog entry

S.LST./OUT./OPT. .... is retained until the end of the task. If the file is assigned to a cataloged (user) file, the contents of the latter are logically deleted, the assignment is retained. Example: /ERASE *SYSLST

162

U3586-J-Z125-7-7600

ERASE

The operands for the ERASE command can be divided into four groups corresponding to the four functional levels.

• Selection operands

The selection operands serve to specify the files or catalog entries to be processed, using attributes stored in the catalog entries as selection criteria. For this reason, some operands of the FSTATUS command can also be specified in the ERASE command.

Attribute Operand

File name pathname

File type

Volume prefix

*SYSfile

*DUMMY

TYPE

POS

FCBTYPE

BLKCTRL

SUPPORT

VOLUME

Operand value

FILE

FGG

AFTER/

BEFORE

NONE

ISAM/SAM/

BTAM/PAM

PUBLIC

PRDISC

TAPE vsn

Function

Specifies the catalog entries to be processed (fully-qualified, partially qualified, with wildcards)

Prefix of all temporary user files

Refers to the EAM object module file

Refers to a system file (SYSLST,

SYSOUT, ...); wildcards are permitted

Refers to a dummy file

No FGGs or file generations are processed

Only file generations or FGGs are processed

Specified with TYPE=FGG; specifies the file generations to be processed

Only catalog entries of unopened files, i.e. of files existing purely as catalog entries, are processed

Files to be processed are selected via their access method

Files to be processed are selected via their file format

Only files on public disk are processed

Only files on private disk are processed

Only tape files are processed

Only files on the volume with volume serial number "vsn" are processed

U3586-J-Z125-7-7600

163

ERASE

164

Attribute Operand

Migration MIGRATE

STORAGE-

LEVEL

Data security

BACKUP and protection ACCESS

INHIBIT

S0/S1/S2

A/B/C/D/E

READ

Storage space

Dates

PASS

EXTENTS

FREESIZE

SIZE

CRDATE

EXDATE

LADATE

Operand value

ALLOWED

WRITE

YES

SPECIAL

NONE

EXPASS

RDPASS

WRPASS

Function

Only files which are allowed to migrate are processed

Only files which are not allowed to migrate are processed

Only files on the specified storage level(s) are processed

Files to be processed are selected via the backup level

Only files with write protection (i.e.

ACCESS=READ) are processed

Only files without write protection are processed

Shareable files are not processed

Only shareable files are processed

Only files which can be accessed under the maintenance user ID are processed.

Only files without password protection are processed

Files to be processed are selected via the type of password protection defined for them

Files to be processed are selected via the number of extents they occupy

Files to be processed are selected via the size of reserved but unused storage space

Files to be processed are selected via the size of reserved storage space

Files to be processed are selected via their creation date

Files to be processed are selected via their expiration date (which implies their retention period)

Files to be processed are selected via their date of last access

U3586-J-Z125-7-7600

ERASE

• File protection operands

File protection operands obviate entry of the CATALOG or PASSWORD commands in order to erase files for which file protection attributes such as passwords, retention period, etc. are defined.

Operand

IGNORE

PASSWORD

Operand value

NONE

ACCESS

EXDATE

NONE password

Function

Protection attributes are evaluated

The protection attribute ACCESS=READ and file protection by BASIC-ACL are ignored

Retention periods are ignored

Password protection is observed

Protection by the specified password is ignored

• Action operands (operands for command execution)

Action operands control the internal execution of the ERASE command. They enable you to specify not only the scope but also the conditions of deletion.

Operand

SPACE-CATALOG

SPACE

DATA

CATALOG

DELETE-OR-EXPORT

DESTROY

MOUNT

Function

The catalog entry is deleted and storage space released

Only storage space is released, the catalog entry is retained

Logical erase: the last-page pointer is reset, the catalog entry and the allocated storage space are retained

Files on private volumes are exported

Files on private volumes are exported, files on public volumes are deleted

The catalog entry is deleted, the storage space is released and cleared

Specifies, for files on private disk, whether all affected disks must be online

U3586-J-Z125-7-7600

165

ERASE

• Control operands

Control operands enable you to define the user interface yourself within certain limits. In interactive mode, for example, you can use prompting, request a SYSOUT listing or have DMS errors ignored (as regards SPIN-OFF).

Operand

CHECK

LIST

NOSTEP

Operand value

MULTIPLE

ERROR

PVS

SINGLE

NO/YES

NONE errcode

Function

All files are erased by ERASE; access is no longer possible (default value for procedures)

Dialog when the catalog or user ID is changed if

"pathname" was not fully-qualified (default value for interactive mode)

Switchover from CHECK=NO to dialog if an error occurs

Dialog when the catalog ID is changed if

"pathname" was not fully-qualified

You decide interactively for each file whether it is to be processed by the current ERASE operation

Erasure is (not) to be logged on SYSOUT

Errors during command execution trigger a

SPIN-OFF

You can specify, via the DMS error code, which errors are not to trigger a SPIN-OFF

166

U3586-J-Z125-7-7600

Format and operand description

Operation

ERASE

Operands pathname prefix

[ *

*SYSfile

*DUMMY

]

ANY

[,TYPE= FILE ][,POS=

FGG

AFTER

BEFORE

]

ANY ANY

[,FCBTYPE=

ISAM

BTAM

( SAM ,...)

PAM

NONE

][,BLKCTRL=

(

PAMKEY

DATA

NONE

,...)

]

ANY

[,SUPPORT= PUBLIC

( PRDISC ,...)

TAPE

][,VOLUME= vsn

][,BACKUP=

( C ,...)

]

ANY

[,ACCESS= READ ][,SHARE=

WRITE

ANY

YES

SPECIAL

][,PASS=

(

NONE

EXPASS

RDPASS

WRPASS

,...)

]

ANY number

[,EXTENTS= (number[,])

(,number)

(number1,number2)

][,FREESIZE=

ANY

SIZE number

(number[,])

(,number)

(number1,number2)

][,SIZE=

ANY

F[REE]SIZE number

(number[,])

(,number)

(number1,number2)

]

[,CRDATE=

ANY

NONE date

(date[,])

(,date)

(date1,date2)

][,EXDATE=

ANY

NONE date

(date[,])

(,date)

(date1,date2)

][,LADATE=

ANY

NONE date

(date[,])

(,date)

(date1,date2)

]

ERASE

U3586-J-Z125-7-7600

167

ERASE

Operation

ERASE

(cont.)

Operands

ANY

[,MIGRATE=

(

ALLOWED

INHIBIT

,...)

NONE

[,IGNORE=

(

ACCESS

EXDATE

,...)

][,PASSWORD=

NONE

ANY

][,STORAGE-LEVEL= S0

( S1 ,...)

(password,...)

SPACE-CATALOG

SPACE

DATA

CATALOG

DELETE-OR-EXPORT

DESTROY

][,MOUNT=

FIRST-DISK

]

ALL-DISKS

[,CHECK=

STD

MULTIPLE

][,LIST=

YES

NONE

][,NOSTEP=

(errcode,...)

]

ERROR

PVS

SINGLE

]

Positional operands

pathname catid userid stands for [:catid:][$userid.][filename]

"pathname" designates the files which are to be erased. You can only erase your own files. Wildcards may be specified in "catid" and

"filename" (cf. the FSTATUS command). If the wildcard "*" is used, it must be entered twice ("**") if it is to include the beginning of a file name.

Catalog ID of the pubset containing the file. If wildcards are used in the catalog ID they are evaluated for the local system only. Catalogs from a foreign system can be addressed only via an explicit "catid".

Default value: the catalog ID assigned to the user ID (JOIN entry).

User ID assigned to the file. Only the user ID of the current job may be specified. Default value: the user ID from the LOGON command.

168

U3586-J-Z125-7-7600

filename prefix

*SYSfile

*DUMMY

ERASE

Designates the files, file generations, FGGs or temporary files to be erased. You may specify a fully or partially qualified file name or use wildcards. The prefix must be included in the names of temporary files; otherwise, temporary files will be ignored.

All temporary files of the job can be erased by specifying the prefix defined for temporary files. If the erase operation is logged or if it is executed via the system dialog, the internal names of the temporary files being processed are displayed on the screen.

The ERASE command refers to the EAM object module file (* file) which is created and used by the language processors. All operands except the control operands (CHECK, LIST, NOSTEP) are checked for formal errors only; otherwise they are ignored when the command is executed. Errors which occur when the * file is erased are ignored.

Designates the system files SYSLST, SYSLSTn, SYSOUT and

SYSOPT (file = LST, LSTn, OUT, OPT; n = 01, 02, ..., 99). The contents of the specified system file or the (user) file to which it is assigned are logically deleted. The file is again written to, starting at the beginning of the file; any previous assignment is retained.

Wildcards may be specified for "file", which means that one ERASE command might be used for several system files. All operands except the control operands (CHECK, LIST, NOSTEP) are checked for format errors but otherwise ignored during execution.

Specifying *SYSOUT is permitted only in batch mode; in interactive mode, it causes a message to be issued, and in procedures, the spin-off mechanism is triggered. If ERASE *SYSLST (or ERASE

*SYSOUT) is immediately followed by a LOGOFF command, logging is suppressed unless it was specifically requested via LIST=YES in the ERASE command or via the OPTION command.

If SYSLST is assigned to a (user) file and has been printed out with

/PRINT *SYSLST,START-SPOOL=..., a subsequent ERASE *SYSLST command logically erases only those records which have been written since the printout.

Designates the dummy file *DUMMY, which is considered to "always exist" and satisfies all selection criteria. All operands except the control operands (CHECK, LIST, NOSTEP) are checked for formal errors but otherwise ignored. If *DUMMY is specified, no catalog or data access takes place. *DUMMY is particularly useful for the testing of procedures.

U3586-J-Z125-7-7600

169

ERASE

Keyword operands (in alphabetical order)

ACCESS

=ANY

=READ

=WRITE

BACKUP

=ANY

Selection operand; the ACCESS value in the catalog entry is used as a selection criterion.

The ACCESS value is not used as a selection criterion; default value.

Only files for which write access is forbidden by ACCESS=READ, i.e. read-only files, are erased.

All files for which write access is permitted are erased.

Selection operand; the files to be erased are selected on the basis of the backup level.

The backup level is not used as a selection criterion; default value.

Only files whose catalog entry contains BACKUP=A are erased.

Only files with BACKUP=B are erased.

Only files with BACKUP=C are erased.

Only files with BACKUP=D are erased.

Only files with BACKUP=E are erased.

BLKCTRL

=ANY

=PAMKEY

=DATA

=NO

=NONE

Selection operand; files to be erased are selected by means of the data format. The data format is determined by the existence and position of the block control field or PAMKEY, both of which contain management information concerning the data block.

The file type is not used as a selection criterion; default value.

Only files which use a separate PAM key are erased.

Only files in which the block control field is located at the beginning of the PAM page are erased.

PAM files: only files which have no block control field are erased.

ISAM and SAM files: only files in which the block control field is located at the beginning of the PAM page are erased.

Only files for which no BLKCTRL value has been defined are erased.

170

U3586-J-Z125-7-7600

ERASE

CATALOG

CHECK

=STD

=NO

=MULTIPLE

Action operand; only for files, file generations and file generation groups on private volumes. The catalog entries of the files explicitly specified or specified as partially qualified or of files selected using wildcards are erased, and their storage space is released but not overwritten. Password protection is observed, but write protection defined via ACCESS=READ or implied by RETPD is ignored; the field DESTROY in the catalog entry is also ignored.

For tape files, "CATALOG" is the default value for the execution of

ERASE.

The action ERASE...,CATALOG is equivalent to exporting files (cf. the

VOLUME operand). These files can be imported again later, either individually using FILE commands containing STATE=FOREIGN or by means of the IMPORT command, which can import one or more files on private disks at the same time. Exclusively reserved files cannot be exported.

Control operand. If specified in interactive mode (or in a dialog procedure), deletion takes place in the course of the dialog. The type of dialog guidance depends on the operand value specified.

Is the default setting, which varies depending on the mode:

CHECK=MULTIPLE is used for interactive mode, but can be changed; CHECK=NO is used for batch mode and cannot be changed.

The deletion procedure cannot be changed. All explicitly specified files or those specified as partially qualified or those selected using wildcards are erased.

If "pathname" is partially qualified or contains wildcards, it is possible, each time the catalog ID is switched, to decide whether or not to erase files from the new catalog. (The response to the system query is either "YES" or "NO". CHECK=MULTIPLE is practical if wildcards are specified for "catid" in "pathname".) ERASE can be terminated interactively (respond with "TERMINATE" to the system query), or the CHECK mode can be changed interactively (

NO/ERROR/SINGLE/PVS).

U3586-J-Z125-7-7600

171

ERASE

=ERROR

=PVS

=SINGLE

CHECK=ERROR is used to specify that a dialog as for

CHECK=SINGLE is to be started if user-correctable errors occur. As long as no errors occur, CHECK=ERROR is equivalent to

CHECK=NO (i.e. no dialog). CHECK=ERROR is set implicitly if

CHECK=SINGLE is selected.

In the event of an error, the error message to abort ERASE processing can be acknowledged (response: "TERMINATE"), or an attempt to rectify the error can be made (response:

"IGNORE="/"PASSWORD="). If desired, the CHECK mode could also be changed ( NO/PVS/SINGLE).

As for CHECK=MULTIPLE, ERASE processing switches to guided dialog if files in different catalogs are affected by the ERASE command. Respond with either "YES" or "NO" to the system query, abort ERASE processing ("TERMINATE") or change the CHECK mode ( NO/ERROR/SINGLE).

For each file which is processed, the user can decide in interactive mode whether or not it is to be erased (response YES/NO). If, in the dialog, protection attributes are specified with "IGNORE" or one or more passwords with "PASSWORD", these specifications are evaluated for the file in question, which is then erased without further queries (explicit "YES"). The user can also abort ERASE processing

(response: "TERMINATE") or change the CHECK mode (

NO/ERROR/PVS).

The affected files are listed in alphanumeric order. If file generation groups are affected, the generations are listed separately in the order of their generation numbers. If you elect not to erase a file generation, processing of the file generation group is terminated and the current status is saved (there must be no gaps in the sequence of file generations).

If only parts of a generation group are to be erased, the order of the generations depends on the value of the POS operand: for

POS=AFTER, the generations are listed in descending order of their generation numbers, starting with the youngest generation; for

POS=BEFORE, they are listed in ascending order of their generation numbers, starting with the oldest generation.

172

U3586-J-Z125-7-7600

ERASE

CRDATE

=ANY

=NONE

=date

=(date[,])

=(,date)

Selection operand; the files to be erased can be selected by means of the creation date. File generation groups and file generations are not included. "CRDATE" corresponds to the catalog field "CRDATE".

The conventions for specifying dates are described under the

FSTATUS command. Range specifications include their limit values.

The creation date is not used as a selection criterion; default value.

Only files whose catalog entry field CRDATE contains the value

NONE are erased, i.e. files which have never been opened.

Only files whose catalog entry field CRDATE contains precisely the specified date are erased.

Only files subjected to write access since the specified date are erased (CRDATE date).

Only files which have not been updated since the specified date are erased (CRDATE date).

=(date1,date2)

DATA

Only files which were last updated during the specified period are erased (date1 CRDATE date2); "date1" and "date2" must not be the same.

Action operand; only for disk files. The data of the affected files is

"logically erased". The catalog entry and the space allocation are retained. The catalog entry is identical to that for a file which has been created with FILE but not yet opened (FCBTYPE=NONE,

CRDATE=NONE). In the case of tape files, the CATALOG operand goes into effect.

DELETE-OR-EXPORT

Action operand; the effects depend on the type of volume on which the files in question are stored:

Files, FGGs, etc. on public volumes: the catalog entry is deleted and the storage space is released (corresponds to the specification "SPACE-CATALOG").

Files, FGGs, etc. on private volumes: only the catalog entry is deleted (corresponds to the specification "CATALOG").

U3586-J-Z125-7-7600

173

ERASE

DESTROY

EXDATE

=ANY

=NONE

=date

=(date[,])

=(,date)

Action operand; only for disk files. The storage space for the affected files is physically erased by overwriting, and then released.

The catalog entry is deleted. In the case of files on private disks, all volumes on which the file was stored must be mounted at erase time.

"Data destruction" (i.e. physical erasure) can also be selected in the

CATALOG command; in this case, DESTROY=YES is set in the catalog entry.

This causes the storage space released to be automatically overwritten. When the file is erased, first the data is overwritten and then the action operands are evaluated. If the file is to be exported

(specification CATALOG or DELETE-OR-EXPORT), the data is not overwritten, since the storage space is not released. In the case of tape files, the CATALOG operand takes effect.

Selection operand; files to be erased are selected by means of the expiration date. The EXDATE field in the catalog entry (cf. the

FSTATUS command indicates the retention period defined for the file if the values in the fields EXDATE and CRDATE are different. File generation groups and file generations are not included.

The conventions for specifying dates are described under the

FSTATUS command. Range specifications include their limit values.

The expiration date is not used as a selection criterion; default value.

Only files whose catalog entry contains no expiration date (i.e. files which have never been opened) are erased.

Only files whose catalog entry field EXDATE contains precisely the specified date are erased.

Only files whose retention period expires on or after the specified date are erased (EXDATE DATE)

All files whose retention period expires on or before the specified are erased (EXDATE date).

=(date1,date2)

Only files whose retention period expires within the specified period are erased (date1 EXDATE date2); "date1" and "date2" must not be the same.

174

U3586-J-Z125-7-7600

ERASE

EXTENTS

=ANY

=number

Selection operand; for disk files only. The files to be processed by

ERASE are selected on the basis of the number of extents. An extent is a contiguous area occupied on disk by a file. The number of extents occupied by a file is shown in the "EXTCNT" field. File generation groups and file generations are not included. "number" must be: 0 number 65535. Range specifications include their limit values.

The number of extents is not used as a selection criterion; default value.

Only disk files with precisely the specified number of extents are erased (EXTCNT=number).

=(number[,])

=(number1, number2)

All disk files occupying a number of extents within the range

"number1" through "number2" are erased ("number1 EXTCNT number2); "number1" and "number2" must not be the same.

=(,number)

Only disk files with at least the specified number of extents are erased (EXTCNT number).

Only disk files with no more than the specified number of extents are processed (EXTCNT number).

FCBTYPE

=ANY

=NONE

=ISAM

=BTAM

Selection operand; files to be erased can be selected by means of the FCBTYPE field of the catalog entry. File generation groups and file generations are not included.

The FCBTYPE is not used as a selection criterion; default value.

Only files for which FCBTYPE=NONE applies are erased, i.e. files which have not yet been opened.

Only ISAM files are erased.

=SAM

=PAM

Only BTAM files are erased. These are tape files, which means that only CATALOG may be used as an action operand (the specification

DELETE-OR-EXPORT is equivalent to CATALOG).

Only SAM files are erased.

Only PAM files are erased.

U3586-J-Z125-7-7600

175

ERASE

FREESIZE

=ANY

=SIZE

=number

=(number[,])

=(,number)

Selection operand; only for disk files. The free PAM pages, i.e. the number of pages reserved for the file but not actually occupied, can then be used to select the files to be erased. File generation groups and file generations are not included.

"number" must be: 0 number 16 777 215. Range specifications are inclusive of their limit values.

The number of free PAM pages is not used as a selection criterion; default value.

Only files which occupy no storage space (i.e. files for which no

PAM page has been written) are erased.

Only files which have precisely the specified number of free PAM pages are erased.

Only files which have at least the specified number of free PAM pages are erased (FREESIZE number).

Only files which have no more than the specified number of free

PAM pages are erased (FREESIZE number).

=(number1, number2)

Only files which have a number of free PAM pages in the range

"number1" through "number2" are erased (number1 FREESIZE number2); "number1" and "number2" must not be the same.

IGNORE File protection operand; this specifies whether the file protection attributes ACCESS=READ and/or EXDATE and file protection with

BASIC-ACL are to be ignored. The specification IGNORE in the

ERASE command thus makes it unnecessary to issue CATALOG commands to reset the protection attributes before the files can be erased.

=NONE

=ACCESS

If the operand values ACCESS and EXDATE are specified in the form of a list, the two protection attributes are ignored (logical OR).

The protection attributes "read-only" (ACCESS=READ) and "retention period" (EXDATE) are observed during erasure; default value.

Files for which ACCESS=READ has been defined or for which access rights have been assigned with BASIC-ACL can still be processed by ERASE.

176

U3586-J-Z125-7-7600

ERASE

=EXDATE Files for which a retention period still exists (EXDATE > current date) may nevertheless be processed by ERASE.

At least 3 letters (EXD) must be entered for EXDATE.

LADATE

=ANY

=NONE

=date

=(date[,])

=(,date)

Selection operand; files to be erased can be selected by means of the last access date. File generation groups and file generations are not included.

The conventions for specifying dates are described under the

FSTATUS command. Range specifications include their limit values.

The LADATE field of the catalog entry is not used as a selection criterion; default value.

Only files whose catalog entry contains LADATE=NONE (i.e. files which have never been opened) are erased.

Only files whose catalog entry field LADATE contains precisely the specified date are erased.

Only files which have been accessed since the specified date

(LADATE date) are erased.

Only files which have not been accessed since the specified date

(LADATE date) are erased.

=(date1,date2)

LIST

=NO

=YES

MIGRATE

Only files which were last accessed within the specified period are erased (date1 LADATE date2); "date1" and "date2" must not be the same.

Control operand; specifies whether successful execution of the

ERASE command is to be logged to SYSOUT. In the event of error, a SYSOUT log with the name of the affected file is always generated.

No (additional) list with the names of the erased files is generated; default value.

A SYSOUT log containing the names of the erased files in alphanumeric order is generated.

Selection operand; the files to be deleted are selected on the basis of the catalog entry in the MIGRATE field. This field indicates whether a file may be migrated from the normal public memory to a background storage level with a slower access time (see the "HSMS" manual).

U3586-J-Z125-7-7600

177

ERASE

=ANY

=ALLOWED

=INHIBIT

MOUNT

The files are deleted regardless of the entry; default value.

Only files which may be migrated are deleted.

Only files which may not be migrated are deleted.

Action operand; only for files on private volumes. This operand is used to reserve the first or all private volumes which are required. It should be specified together with the SPACE-CATALOG or

DESTROY operand. In the case of tape files or files on public disks, this operand is ignored.

=FIRST-DISK Only the private disk containing the beginning of the file and the catalog entry must be online; default value.

=ALL-DISK All private disks on which sections of the file are stored must be online. If any disk is missing, the file is not erased and a SPIN-OFF is triggered after termination of ERASE processing.

NOSTEP

=NONE

=errcode

Control operand: in procedures, this can be used to specify whether a SPIN-OFF is to be triggered for all errors or whether -- and, if so, which -- error conditions may be ignored. If an error occurs during deletion of a system file, no SPIN-OFF is normally triggered, regardless of the setting for NOSTEP.

All errors trigger a SPIN-OFF; default value.

This can be used in conjunction with the DMS error code to specify errors which are to be ignored, i.e. which are not to cause abnormal termination of the command and to trigger a SPIN-OFF.

The DMS error code consists of 7 characters, the first three of which are always "DMS". The last four characters identify the error. The error codes specified by the user are not checked for validity as they are entered.

PASS

=ANY

=NONE

=EXPASS

A list of up to three DMS error codes which are to be ignored can be specified here.

Selection operand; selects the files to be erased via the type of password.

The type of password protection is not used as a selection criterion; default value.

Only files for which no password has been defined are erased.

Only files protected by an execute password are erased.

178

U3586-J-Z125-7-7600

ERASE

=RDPASS

=WRPASS

PASSWORD

=NONE

=password

POS

=AFTER

=BEFORE

=ANY

=NO

Only files protected by a read password are erased.

Only files protected by a write password are erased.

File protection operand; specifies one or more passwords, thus permitting files protected by these passwords to be erased. The passwords entered here are not entered in the password table for the job, and are thus valid only for the current ERASE command.

The passwords must comply with the rules for password definition; in logs they are replaced by the letter "P".

No passwords are specified in the ERASE command; default value.

Protection by this password is to be revoked.

Specification of a password whose binary code is X’00’ is equivalent to PASS=NONE. A list of up to three passwords may be specified.

Selection operand; only for file generations. Wildcards may be used everywhere in "pathname" except in the generation number, which must be entered as an absolute or relative generation number. The generation identified by "pathname" must exist and is not erased.

Depending on the operand value AFTER/BEFORE, all younger or all older file generations are erased. The following fields of the catalog entry are updated:

FIRSTGN if the oldest generation is erased; the generation specified in "pathname" becomes the oldest generation.

LASTGN if the youngest generation is erased; the generation specified in "pathname" becomes the youngest generation.

BASE if the generation with relative generation number 0 is erased; the generation specified in "pathname" becomes the base generation.

All generations selected by "pathname" and with a generation number greater than that specified in "pathname" are erased.

All generations selected by "pathname" and with a generation number less than that specified in "pathname" are erased.

Selection operand; can be used to specify the shareability of a file as a selection criterion.

Shareability is not used as a selection criterion; default value.

Only files which are not shareable, i.e. which only the user can access, are erased.

U3586-J-Z125-7-7600

179

ERASE

=YES

=SPECIAL

SIZE

=ANY

=FREESIZE

=number

Only shareable files are erased.

Only files which can be accessed under the maintenance user ID are processed.

Selection operand; only for disk files. This is used to select files to be erased via the file size or the size of the reserved space (= number of PAM pages). File generations and file generation groups are not included.

"number" specifies a number of PAM pages, where 0 number

16777215. Range specifications include their limit values.

The file size is not used as a selection criterion; default value.

Only files for which space has been reserved but not actually used

(LASTPG = 0) are erased, i.e. files which have not yet been opened.

Only files for which precisely the specified number of PAM pages have been reserved are erased.

=(number[,])

=(,number)

Only files for which at least the specified number of PAM pages have been reserved are erased (SIZE number).

Only files for which no more than the specified number of PAM pages have been reserved are erased (SIZE number).

=(number1,number2)

All files for which a number of PAM pages in the range "number1" through "number2" have been reserved are erased.

SPACE Action operand; only for files on public disk. The storage space for the files affected by ERASE is released, while the catalog entry is retained but updated: it is then identical to that of a file that has never been opened (FCBTYPE=NONE, CRDATE=NONE). The

SPACE operand is rejected for files on private disk. In the case of tape files, the CATALOG operand goes into effect.

SPACE-CATALOG Action operand; default value for ERASE for disk files. The catalog entries for the affected files are deleted and their storage space is released.

180

U3586-J-Z125-7-7600

ERASE

STORAGE-LEVEL Selection parameter; selects files to be processed based on the storage level on which they are stored (see the "HSMS" manual).

=ANY

=S0

=S1

The storage level is not used as a selection criterion; default value.

Only the files on storage level S0 are erased.

=S2

Only the files on storage level S1 are erased. Since only the entries in the system catalog are actually deleted, the files can be restored by means of ARCHIVE or HSMS (Hierarchical Storage Management

System).

Only the files on storage level S2 are erased. Since only the entries in the system catalog are actually deleted, the files can be restored by means of ARCHIVE or HSMS (Hierarchical Storage Management

System).

SUPPORT

=ANY

=PUBLIC

=PRDISC

=TAPE

Selection operand; used to select the files to be erased via the volume type. File generation groups and file generations are not included.

The volume type is not used as a selection criterion; default value.

Only files on public disks are erased.

Only files on private disks are erased.

Only files on tapes or tape cartridges are erased.

TYPE

=ANY

=FILE

=FGG

Selection operand; specifies the file type and thus determines the extent to which ERASE selection criteria are evaluated, since not all selection operands include FGGs and file generations.

"Normal" files, file generations and file generation groups are erased.

However, FGGs and file generations are ignored by some of the selection operands in order to avoid creating gaps in the sequence of generations; default value.

File generation groups and file generations are not erased; all other selection operands are evaluated.

Only file generation groups and file generations are erased. Only selection operands which refer to attributes that are the same for all generations of an FGG (ACCESS, BACKUP, PASS, SHARE, EXDATE,

SUPPORT=PRDISC) should be specified together with TYPE=FGG.

All other selection operands are ignored in connection with FGGs and file generations.

U3586-J-Z125-7-7600

181

ERASE

VOLUME

=ANY

=vsn

Selection operand; only for files on private volume. By specifying the

VSN of a volume, the user can define that only files on this volume are to be erased.

The VOLUME operand has a special function when specified together with the action operand CATALOG. If VOLUME indicates a private disk, individual file generations can be exported with ERASE

CATALOG, VOLUME=vsn, which means that gaps are left in an

FGG. If VOLUME indicates a tape or if VOLUME is specified without

CATALOG, FGGs and file generations are ignored.

If VOLUME is used together with the action operands SPACE-

CATALOG, SPACE, DESTROY or DATA, or for tapes, FGGs and file generations are ignored.

Volumes are not used as a selection criterion; default value.

All files which are stored on the specified volume or have dummy entries on this volume are erased. In this case, "pathname" does not need to be specified.

If VOLUME=vsn is specified together with the action operand

CATALOG and VOLUME indicates a private disk, FGGs and file generations are also deleted.

The user should ensure that the exporting of generations does not leave gaps in the generation sequence of an FGG.

The combination ERASE [pathname], CATALOG, VOLUME=vsn is the "reverse" function to that of the IMPORT command (q.v.).

Whereas "ERASE, CATALOG, VOLUME" exports all files which occupy storage space on the specified volume, the IMPORT command imports only those files which begin on the specified volume.

182

U3586-J-Z125-7-7600

ERASE

Examples

Example 1:

Erasing files with a partially-qualified file name

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

ERASE MAX.PROTO.,CHECK=SINGLE

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.PROTO.CREATE-POOL’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITITIONAL OPTIONS)?

% DMS0517 DELETE FUNCTION WITHDRAWN BY CALLER

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.PROTO.DEL-F-GROUP.1’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

% DMS0801 ERASE ERROR ON FILE :W:$US123456.MAX.PROTO.DEL-F-GROUP.1

% DMS05BF FILE PASSWORD-PROTECTED. FIRST ENTER CORRECT PASSWORD WITH

APPROPRIATE COMMAND, THEN REENTER /DELETE-FILE OR /ERASE

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.PROTO.DEL-F-GROUP.1’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

% DMS0516 ERASE FILE(S) ’(&00)’ ? REPLY (Y=YES; N=NO; T=TERMINATE

CMD; ?=EXPL. OF ADDITIONAL OPTIONS)

% - The user can decide, in dialog mode, whether the erase task requested

% - is to be processed or not.

% - (&00): Partially qualified file name, file name, name of file

% generation or file generation group.

% - Y: The file or file generation or file generation group will be

% erased.

% - N: This at times displayed file or file generation or file

% generation group will not be erased.

% - T: The erase command entered will not be processed any further.

% - ?: The explanation of the additional options will be displayed following

% -

% the request which will be offered once more.

The meaning of the operands of the additional options permitted

% -

% is analogous to that of the corresponding operands in the command and may be looked up in the reference manual ’Control System Command

% -

% language’.

Additional options which may be added with comma to the reply

(’Y’ or ’N’ or ’T’):

% - ,CHECK: Update of the current dialog mode:

% ,CHECK=NO or =PVS or =MULTIPLE or =SINGLE or =ERROR.

% - ,IGNORE: Re-issue of the protection attribute before the erase job is

% -

% processed:

,IGNORE=ACCESS or =EXDATE or ,IGNORE=(ACCESS,EXDATE).

% - ,PASSWORD: Re-issued of passwords before erase job is processed.

% Only maximum of 3 passwords is allowed hexadecimally or

% numeric.

% ,PASSWORD=password or =(password,...).

% - Enter reply corresponding to the explanation in the meaning text.

% - If the reply is invalid, or if an empty string is entered, the task

% - will not be processed.

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.PROTO.DEL-F-GROUP.1’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

% DMS0517 DELETE FUNCTION WITHDRAWN BY CALLER

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.PROTO.DEL-F-GROUP.21’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.PROTO.ERASE.1’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

% DMS0801 ERASE ERROR ON FILE :W:$US123456.MAX.PROTO.ERASE.1

% DMS06D5 THE FILE IS READ ONLY ACCESS. COMMAND TERMINATED

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.PROTO.ERASE.1’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

Y,IGNORE=ACCESS

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.PROTO.ERASE.2’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

% DMS0801 ERASE ERROR ON FILE :W:$US123456.MAX.PROTO.ERASE.2

% DMS05C3 FILE TO BE DELETED IS IN USE. RETRY COMMAND LATER

FSTATUS MAX.PROTO.

00000000 :W:$US123456.MAX.PROTO.CREATE-POOL

00000024 :W:$US123456.MAX.PROTO.DEL-F-GROUP.1

U3586-J-Z125-7-7600

183

ERASE

(IN)

(OUT)

00000024 :W:$US123456.MAX.PROTO.ERASE.2

:W: PUBLIC: 3 FILES. RES= 48, FREE=

ERASE MAX.PROTO.DEL-F-GROUP.1,PASSWORD=P

FSTAT MAX.PROTO.

00000000 :W:$US123456.MAX.PROTO.CREATE-POOL

00000024 :W:$US123456.MAX.PROTO.ERASE.2

:W: PUBLIC: 2 FILES. RES= 24, FREE=

35, REL=

24, REL=

33 PAGES

24 PAGES

A number of files which were created as logging files are to be erased (subname:

PROTO). The file MAX.PROTO.CREATE.POOL is to be retained. The file

MAX.PROTO.DEL-F-GROUP.21 is password-protected, the file MAX.PROTO.ERASE.1

has write protection, MAX.PROTO.ERASE.2 is locked. User prompting is requested during execution.

Finally, the file MAX.PROTO.DEL-F-GROUP.21 is erased with the PASSWORD operand.

184

U3586-J-Z125-7-7600

ERASE

Example 2

: Wildcard *

(IN)

(OUT)

FSTAT ,CRDAT=+0

00000003 :W:$US123456.MAX.TEST.1

00000003 :W:$US123456.MAX.TEST.2

:W: PUBLIC: 2 FILES. RES= 6, FREE= 4, REL= 0 PAGES

(IN)

(OUT)

(IN)

(OUT)

ERASE **,CRDAT=+0,LIST=YES

% DMS0516 ERASE FILE(S) ’:W:$US123456.**’ ? REPLY (Y=YES; N=NO;

T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

% DMS0800 SPECIFIED FILE ’:W:$US123456.MAX.TEST.1’ ERASED

% DMS0800 SPECIFIED FILE ’:W:$US123456.MAX.TEST.2’ ERASED

/ERASE ** erases all files under the user ID ( FSTAT *); the selection is in this case restricted by the CRDATE operand (ERASE * would erase the object module file of the job).

/ERASE *SYSLST would erase system file SYSLST, /ERASE **SYSLST would erase all files whose file name ends with the character string SYSLST.

Example 3:

Selection operands

(IN) FS MAX.*ASS.

(OUT) 00000000 :W:$US123456.MAX.Q.ASS.DSECTS

00000000 :W:$US123456.MAX.Q.ASS.DSECTS3

00000003 :W:$US123456.MAX.T1ASS.FILE

:W: PUBLIC: 3 FILES. RES= 3, FREE= 2, REL= 0 PAGES

(IN) ERASE *ASS.,SIZE=(0,),LIST=YES,CHECK=SINGLE

(OUT) % DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.Q.ASS.DSECTS’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

(IN) Y

(OUT) % DMS0800 SPECIFIED FILE ’:W:$US123456.MAX.Q.ASS.DSECTS’ ERASED

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.Q.ASS.DSECTS3’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

(IN) N

(OUT) % DMS0517 DELETE FUNCTION WITHDRAWN BY CALLER

% DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.T1ASS.FILE’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

Y (IN)

(OUT) % DMS0800 SPECIFIED FILE ’:W:$US123456.MAX.T1ASS.FILE’ ERASED

(IN) FSTAT MAX.

(OUT) 00000003 :W:$US123456.MAX.MESS.SHORT

00000024 :W:$US123456.MAX.PROTO.ERASE.2

00000000 :W:$US123456.MAX.Q.ASS.DSECTS3

00000000 :W:$US123456.MAX.TEST.GROUP.1 (FGG)

:W: PUBLIC: 4 FILES. RES= 27, FREE= 20, REL= 15 PAGES

U3586-J-Z125-7-7600

185

ERASE

Example 4:

Deleting file generations

(IN) FSTATUS MAX.,TYPE=FGG,GEN=YES

(OUT) 00000000 :W:$US123456.MAX.GROUP.RES (FGG)

00000003 :W:$US123456.MAX.GROUP.RES(*0002)

00000003 :W:$US123456.MAX.GROUP.RES(*0003)

00000003 :W:$US123456.MAX.GROUP.RES(*0004)

00000003 :W:$US123456.MAX.GROUP.RES(*0005)

00000003 :W:$US123456.MAX.GROUP.RES(*0006)

00000000 :W:$US123456.MAX.TEST.GROUP.1 (FGG)

00000003 :W:$US123456.MAX.TEST.GROUP.1(*0009)

:W: PUBLIC: 8 FILES. RES= 18, FREE= 12, REL= 0 PAGES

(IN) ERASE MAX.*GR*(*4),TYPE=FGG,POS=AFTER,LIST=YES

(OUT) % DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.*GR*(*0004)’ ?

REPLY (Y=YES; N=NO; T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

(IN) Y

(OUT) % DMS0800 SPECIFIED FILE ’:W:$US123456.MAX.GROUP.RES(*0006)’ ERASED

% DMS0800 SPECIFIED FILE ’:W:$US123456.MAX.GROUP.RES(*0005)’ ERASED

% DMS0801 ERASE ERROR ON FILE :W:$US123456.MAX.TEST.GROUP.1

% DMS06C7 USER ATTEMPTED TO PROCESS A GENERATION WITH AN INCORRECT

GENERATION NUMBER. COMMAND TERMINATED

186

U3586-J-Z125-7-7600

ERASE

Example 5:

Exporting files to private disk

(IN) FSTAT ,SUPPORT=PRDISC

(OUT) 00000003*:W:$US123456.MAX.PRIV.DAT.1

00000003*:W:$US123456.MAX.PRIV.DAT.2

00000003*:W:$US123456.MAX.PRIV.DAT.3

00000003*:W:$US123456.MAX.PRIV.DAT.4

00000003*:W:$US123456.MAX.PRIV.DAT.5

:W: PRIVATE: 5 FILES. RES= 15, FREE= 10, REL= 0 PAGES

(IN) ERASE ,DELETE-OR-EXPORT,VOLUME=WORK02

(OUT) % DMS0516 ERASE FILE(S) ’:W:$US123456.’ ? REPLY (Y=YES; N=NO;

T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

(IN) N

(OUT) % DMS0517 DELETE FUNCTION WITHDRAWN BY CALLER

(IN) ERASE MAX.,DELETE-OR-EXPORT,VOLUME=WORK01

(OUT) % DMS0516 ERASE FILE(S) ’:W:$US123456.MAX.’ ? REPLY (Y=YES; N=NO;

T=TERMINATE CMD; ?=EXPL. OF ADDITIONAL OPTIONS)?

(IN) Y

(IN) FSTAT ,SUPPORT=PRDISC

(OUT) 0000003*:W:$US123456.MAX.PRIV.DAT.5

:W: PRIVATE: 1 FILE.

RES= 3, FREE= 2, REL= 0 PAGES

(IN) IMPORT ,VOLUME=WORK01,DEVICE=D3480,LIST=(YES,SYSOUT)

(OUT) 0 :W:$US123456.MAX.PRIV.DAT.1

0 :W:$US123456.MAX.PRIV.DAT.2

0 :W:$US123456.MAX.PRIV.DAT.3

(IN)

0 :W:$US123456.MAX.PRIV.DAT.4

FSTAT ,SUPPORT=PRDISC

(OUT) 00000003*:W:$US123456.MAX.PRIV.DAT.1

00000003*:W:$US123456.MAX.PRIV.DAT.2

00000003*:W:$US123456.MAX.PRIV.DAT.3

00000003*:W:$US123456.MAX.PRIV.DAT.4

00000003*:W:$US123456.MAX.PRIV.DAT.5

:W: PRIVATE: 5 FILES. RES= 15, FREE= 10, REL= 0 PAGES

U3586-J-Z125-7-7600

187

ESCAPE

ESCAPE Interrupt procedure

Command description

The ESCAPE command has the same effect as the ESCAPE function (pressing K2 key).

A procedure is interrupted at the point where an ESCAPE command is encountered, and a message is displayed on the screen, giving the level number of the interrupted procedure:

TASK IS IN ESCAPE MODE AT LEVEL NUMBER I

I = 0

I = 1

I = 2 indicates level 0 (primary command input) indicates level 1 indicates level 2 etc.

You can subsequently enter commands from the terminal. ESCAPE mode remains in force until left by means of the RTI or the ABORT command.

This command is only valid in interactive mode and can only be used in a procedure. It is ignored in batch mode.

Nesting of interrupts is permissible (see examples). A procedure called in ESCAPE mode can also be interrupted by means of an ESCAPE command or ESCAPE function.

In this case, the first interrupt is not lost (see example 4).

In ESCAPE mode, the symbolic operands which were defined in the interrupted procedure are accessible to users, and may be entered from the terminal. However, a command with a symbolic operand which has been replaced by the appropriate value is only listed if a log for the interrupted procedure was requested (see example 5).

Format

Operation

ESCAPE

Operands

The command is entered without operands.

188

U3586-J-Z125-7-7600

Examples

Example 1:

Execution of an ENDP command in ESCAPE mode

ESCAPE

Fig. ESCAPE-1 ENDP command in ESCAPE mode

Assignment of SYSCMD

1) Command "/CALL PROC1" assigns SYSCMD to the procedure file PROC1.

2) Command "/CALL PROC2" assigns SYSCMD to the procedure file PROC2.

3) After ESCAPE processing has been initiated, SYSCMD is assigned to the terminal.

4) SYSCMD is still on the data display terminal (ESCAPE mode retained). A branch is made from procedure level 2 to procedure level 1.

5) The RTI command terminates ESCAPE mode. SYSCMD returns to the procedure file PROC1.

6) SYSCMD is reassigned to primary command input.

U3586-J-Z125-7-7600

189

ESCAPE

Example 2:

Execution of a CALL command in ESCAPE mode

190

Fig. ESCAPE-2 CALL command in ESCAPE mode

Assignment of SYSCMD

1) Command "/CALL PROC1" assigns SYSCMD to the procedure file PROC1.

2) After ESCAPE processing has been initiated, SYSCMD is assigned to the data display terminal.

3) Command "/CALL PROC2" assigns SYSCMD to the procedure file PROC2.

4) SYSCMD is still on the data display terminal (ESCAPE mode retained). A branch is made from procedure level 2 to procedure level 1.

5) The RTI command terminates ESCAPE mode. SYSCMD returns to the procedure file PROC1.

6) SYSCMD is reassigned to primary command input.

U3586-J-Z125-7-7600

Example 3:

Execution of a DO command in ESCAPE mode

ESCAPE

Fig. ESCAPE-3 DO command in ESCAPE mode

Assignment of SYSCMD

1) Command "/CALL PROC1" assigns SYSCMD to the procedure file PROC1.

2) Command "/CALL PROC2" assigns SYSCMD to the procedure file PROC2.

3) After ESCAPE processing, SYSCMD is assigned to the data display terminal.

4) Command "/DO PROC3" assigns SYSCMD to the procedure file PROC3, but there is no further nesting (level 2 is retained).

5) SYSCMD is returned to the data display terminal (ESCAPE mode is not terminated). A branch is made from procedure level 2 to procedure level 1.

6) The RTI command terminates ESCAPE mode. SYSCMD is once more on the procedure file PROC1.

7) SYSCMD is reassigned to primary command input.

U3586-J-Z125-7-7600

191

ESCAPE

Example 4:

Nesting of ESCAPE levels

192

Fig. ESCAPE-4 Nesting of ESCAPE levels

Assignment of SYSCMD

1) Command "/CALL PROC1" assigns SYSCMD to the procedure file PROC1.

2) SYSCMD is then assigned to the data display terminal, after ESCAPE processing has been initiated.

3) Command "/CALL PROC2" assigns SYSCMD to the procedure file PROC2.

4) SYSCMD is then assigned to the data display terminal, after ESCAPE processing has been initiated.

5) SYSCMD is assigned to the procedure file PROC2.

6) SYSCMD is assigned to the data display terminal (ESCAPE mode for 1st level still in force).

7) Command RTI assigns SYSCMD to the procedure file PROC1.

8) SYSCMD is returned to primary command input.

U3586-J-Z125-7-7600

Example 5:

Use of symbolic parameters in ESCAPE mode

ESCAPE

Fig. ESCAPE-5 Symbolic parameters in ESCAPE mode

The arrows show the path of the system file SYSCMD. When the PROC1 procedure is called by the CALL command, the file name "TEST" is entered for the operand "&DAT".

After exiting procedure mode by means of the ESCAPE command, the user issues the

SYSFILE command at the terminal, using the symbolic parameter "&DAT". Since command logging to SYSOUT was requested for the PROC1 procedure file (operand C specified in the PROCEDURE command), this command will be logged to SYSOUT even in ESCAPE mode, complete with the appropriate value for TEST.

U3586-J-Z125-7-7600

193

EXECUTE

EXECUTE Load and start program

Command description

The EXECUTE command links object modules and link load modules, reads them to memory and initiates them (dynamic linking loader (DLL) call; format 1), reads load modules to memory and initiates them

(static linking loader (ELDE) call; format 2).

If the program is to be loaded but not yet initiated, use the LOAD command.

An object module (linkable module) is produced when a source program is compiled.

An object module is stored: temporarily in the * file (temporary EAM object module file), permanently in an object module library, OML, (library routines LMR/LMS), permanently as an R-type member in a program library, PL,

(library routine LMS).

Aload module is produced when one or more object modules are linked to form an executable program. A load module is stored: as a cataloged file (output file of the linkage editor TSOSLNK), as a C-type member in a program library.

A link load module (LLM) comprises a number of modules linked by the LINKAGE

EDITOR. It has the attributes of both prelinked modules (large modules) and programs

(load modules) generated by the TSOSLNK linkage editor, which results in optimum loading time. For further details refer to the "Linkage Editor and Loaders" manual [22].

The Dynamic Linking Loader (DLL) links object modules into a load module, reads this module into memory and initiates the program run. The ELDE loader reads a load module into memory and initiates the program run.

The system messages providing information about the load operation (BLS0500,

BLS0517, ...) can be suppressed by activating job switch 4. For a detailed description, see the "Linkage Editor and Loaders" manual [22] and the "LMS" manual [14].

The execution of programs cannot be nested.

If an EXECUTE command is issued while a program is loaded, the loaded program is unloaded and the EXECUTE command is executed. Although no error flag is displayed an ABEND-STXIT routine defined in the unloaded program is activated, unless the

EXEC command was called via the CMD macro (see the "Executive Macros" manual

[5]).

194

U3586-J-Z125-7-7600

EXECUTE

Program monitoring

When the EXECUTE command is issued, the status indicator in the program-monitoring job variable is set to "$R".

If a program has already been loaded (and perhaps interrupted by the BREAK command), the status indicator in the job variable monitoring this program is set to

"$A".

If the job variable is not accessible at command execution time, an error message is output to SYSOUT and command execution continued.

U3586-J-Z125-7-7600

195

EXECUTE

Formats and operand description (identical to those of LOAD command)

Format 1:

Calling the Dynamic Linking Loader DLL

Operation

EXECUTE

Operands

(entry[,

*LINK([LINK=]linkname) pathname

])

{*STD

(module[(VERSION=]{

{version

)[,

*LINK([LINK=]linkname) pathname

)]

[,TIME=t][,MONJV=jvname]

IDA=

YES

ALL

SYMTEST=

]

[,PROG-MOD=

ANY

]

[,RUN-MOD=

STD

ADVANCED([LOAD-INF=

DEFINITIONS

MAP

NONE

REFERENCES

][,ALTLIB=

YES

[,NAME-COL=

STD

ABORT

STD

][,UNRES= DELAY ][,ERREXIT=address]

ABORT

INFORMATION

[,CTRL-MSG= WARNING

ERROR

][MAP=

NO number

SYSOUT

BOTH[(number)]

][,SHARE=

SYSTEM

NONE

])

]

[,VSPACE=(a[,b])]

TASK-STD

[,VPWAIT= number

]

196

U3586-J-Z125-7-7600

* entry module pathname catid userid modulelib

EXECUTE

The asterisk designates the task’s temporary EAM object module file.

The modules in this file are linked to form a program. If the object module library contains a number of modules of the same name, only the first module is loaded.

Name of an entry point (ENTRY) or CSECT statement in a program.

The object module with "entry" is loaded and executed from the point of entry, provided no operand is specified in the END statement. If the END statement contains an operand, its address always serves as the start address.

Name of a module (object module or LLM) or library member to be loaded by DLL. "module" may be up to 32 characters in length.

stands for: [:catid:][$userid.]modulelib

Catalog ID of the pubset on which the file is stored.

Default value: the catalog ID assigned to the user ID (JOIN entry).

User ID to which the file is assigned.

Default value: the user ID from the LOGON command.

Name of the library containing the specified object module.

This library may be an object module library (OML) or a program library with members of type R and L. If "libname" and "linkname" are not specified with RUN-MOD=ADVANCED, the library assigned to link name BLSLIB is searched.

If "libname" is not specified with RUN-MOD=STD, the TASKLIB library is searched by the operating system.

It is not possible to process an LLM with RUN-MOD=STD.

If the library (file) is not cataloged under the user’s ID, it must be shareable (operand SHARE=YES in the CATALOG command), and the user ID must be specified.

If the "pathname" entry is missing or the required object module is not found there, it is searched for in the following files in the specified sequence:

1. $TSOS.modlib or $TSOS.library;

2. File assigned to the (system) file TASKLIB (/SYSFILE

TASKLIB=....);

3. (User) file with the name TASKLIB;

4. $TSOS.TASKLIB. (no search through this file if there is a (user) file with the name TASKLIB).

U3586-J-Z125-7-7600

197

EXECUTE

IDA

=YES

=NO

Allows the use of symbolic addresses for debugging programs with the aid of IDA commands, provided that an internal symbol dictionary exists for the program at that time.

You can have this internal symbol dictionary created by entering the corresponding operand in the COMOPT statement; e.g. "*COMOPT

ISD" for the assembler.

The internal symbol dictionary is used.

The internal symbol dictionary is ignored; default value

LINK=linkname Specifies the link name assigned to a library. LINK=linkname is only permitted for RUN-MOD=ADVANCED and must be specified with

*LINK(..) instead of a library name.

MONJV

=jvname

PROG-MOD

=24

Specifies a job variable, which serves to monitor the program run.

The operating system enters the program’s processing state in the job variable ($R, $T, $A job initiated, job terminated normally, job terminated abnormally). The STATUS MONJV=... command, for example, could then be used to check this state. Note that the job variable must be cataloged before calling this command. For information about job variables please refer to the "Job Variables" manual [11]. Job variables cannot be used unless the JV software product is installed.

Name of the job variable.

Of significance only on XS31 systems. This operand is ignored on non-XS31 systems. PROG-MOD specifies the area of class 6 memory (above or below the 16-Mb boundary) into which the program is loaded. The correlation between the addressing mode

(AMODE) and load mode (RMODE) specified in the program must be taken into account. (AMODE and RMODE denote statements in an assembler program.)

The module is loaded below the 16-Mb boundary. The program is executed in 24-bit addressing mode. External references are interpreted as 24-bit addresses. Loading of a program with the attribute AMODE=31 is aborted with an error message; this also applies to the loading of a load unit if the control section has the attribute AMODE=31. 24 is the default value.

198

U3586-J-Z125-7-7600

EXECUTE

=ANY The load address is established as follows by combining the addressing and load modes specified in the program:

RMODE

ANY

16-Mb boundary

Error

AMODE

31 ANY

16-Mb boundary 16-Mb boundary

> 16-Mb boundary > 16-Mb boundary

Where:

16-Mb boundary:

> 16-Mb boundary: below the 16-Mb boundary.

above the 16-Mb boundary.

Error: illegal combination; error message during program compilation.

RUN-MOD

=STD

Defines the operating mode of the Dynamic Linking Loader DLL.

The DLL operates in a mode that is fully compatible with previous

BS2000 versions (DLL of BS2000 versions prior to version 10.0A).

=ADVANCED(..) DLL operates in a mode that supports the new functions (as of

BS2000 V10.0A). These new functions may produce incompatibilities in the case of existing modules.

ALTLIB=YES|NO

Specifies whether alternative libraries are to be searched. Alternative libraries are assigned via the link name BLSnn (00 nn 99). They are also used for the autolink function of DLL.

NAME-COL Defines how name conflicts are to be handled in the case of identically named symbols. Name conflicts are only detected if the symbols are not masked.

=STD Name conflicts between unmasked symbols are indicated by means of warnings. The module containing the symbol of the same name is loaded. The new version of the symbol is masked, i.e. is no longer used to satisfy external references.

=ABORT Loading of the current load unit is aborted if a name collision between unmasked symbols is detected.

U3586-J-Z125-7-7600

199

EXECUTE

200

UNRES

=STD

Defines how unresolved external references are to be treated. All unresolved external symbols are output to the symbol file SYSOUT.

Unresolved external dummy sections (XDSECs-R) are listed separately.

Unresolved external references receive an address specified in the

ERROR-EXIT operand.

=DELAY Unresolved external references are satisfied later. This operand is only permitted for LOAD-INFORMATION=REFERENCES.

DLL stores the unresolved external references in the link context. If the next load unit is loaded in this context, DLL will then attempt to satisfy the stored external references with the CSECTs and ENTRYs of this load unit. This process is repeated when further load units are loaded, as long as the context exists. External dummy sections

(XDSECs-R) cannot be stored.

When unresolved external references are stored in the link context, they are assigned a (provisional) address that is specified in the

ERROR-EXIT operand.

=ABORT Unresolved external references are not permitted. Loading of the current load unit is aborted.

ERREXIT=address

Defines the address that is assigned to the unresolved external references if the operands UNRESOLVED-EXTRNS=STD / DELAY are specified.

The value X’FFFFFFFF’ is used by default.

CTRL-MSG Defines the lowest message class as of which messages are to be output.

=INFORMATION

Messages of all message classes are output.

=WARNING Only messages of message class WARNING and ERROR are output.

Messages of the INFORMATION class are suppressed.

=ERROR Only messages of the message class ERROR are output.

LOAD-INF Defines the load information of the load unit.

=DEFINITIONS

Loads an ESD containing the program definitions of all modules of the load unit.

Program definitions are control sections (CSECTs), entry points

(ENTRYs), COMMON areas, and external dummy sections (XDSECs-

D).

U3586-J-Z125-7-7600

EXECUTE

=REFERENCES

Loads an ESD containing not only the program definitions but also the resolved references of all modules of the load unit.

References are external references (EXTRNs), V-type constants, conditional external references (WXTRNs), and external dummy sections (XDSECs-R).

=MAP Only one ESD, which is required to create the DLL listing, is loaded

temporarily

. The ESD is unloaded as soon as the DLL listing has been generated.

=NONE

MAP

No ESD is loaded.

Specifies whether or not a DLL listing is to be output and defines the output destination.

No DLL listing is output.

=NO

=num The output destination is a system file SYSLST from the set

SYSLST01 through SYSLST99 (where 1 num 99).

=SYSOUT The output destination is the system file SYSOUT.

=BOTH[(num)]

Defines the output destination as the system file SYSOUT and

SYSLST. "num" specifies the number of the system file SYSLST from the set SYSLST01 through SYSLST99.

SHARE Specifies whether or not an unprivileged subsystem (see the "System

Installation" manual) and share programs are to be considered by

DLL during searching. This also applies to the autolink function of

DLL.

=SYSTEM DLL first searches in an unprivileged subsystem and then in share programs.

=NONE Any unprivileged subsystem and share programs are skipped by DLL during a search.

SYMTEST

=ALL

This operand is required for debugging with AID.

SYMTEST=ALL allows the use of symbolic addresses for program debugging with AID commands. This requires that a local or internal symbol dictionary be generated at program compilation time.

U3586-J-Z125-7-7600

201

EXECUTE

=NO

TIME

The symbolic address table or internal symbol dictionary is ignored; default value.

Defines a maximum CPU time for the program run. The resulting behavior is different in interactive and batch mode:

Interactive mode:

After the specified time has expired, the program is interrupted and a user prompt asks whether you require a program dump. If no program dump is required, the user can opt to continue the program run, or abort. The time specified with TIME=... is not compared with that of the LOGON command. If TIME=... is not specified, the program run is not interrupted - irrespective of the time specification, if any, in the LOGON command.

Batch mode:

The program run is aborted once the specified time has expired.

The program is not loaded if the specified time exceeds the CPU time still available to the task at that moment (ENTER-JOB-

/LOGON command/default value). This latter specification is the maximum program run time (CPU time) unless otherwise defined by means of TIME; once this time has expired, the program run is aborted and the task terminated.

Time specification in seconds; 0 t 32767.

If the operand TIME=NTL has been specified in the LOGON or

ENTER command, the "t" entry is ignored.

VPSPACE=(a[,b]) Only permitted for vector-based computers; specifies the required vector storage space, either above ("a") or below ("b") the 16 Mb boundary. "a" and "b" are integers.

VPWAIT Only permitted for vector-based computers; defines the maximum waiting time (in minutes) that may be used by the job for the reservation of storage space. The command is rejected when the waiting time has expired.

=TASK-STD

=num

The command is rejected in interactive mode if the reservation of vector storage space is not possible.

There is no restriction on the waiting time in batch mode.

Specifies the waiting time in numbers of seconds.

202

U3586-J-Z125-7-7600

EXECUTE

Format 2: Calling the static loader ELDE

Operation

EXECUTE

Operands pathname

LIBRARY=pathname,ELEMENT=member[(VERSION= version

*STD

)]

[,CLASSII=(max[,min[,p]])]

[,TIME=t]

IDA=

YES

ALL

SYMTEST=

[,MONJV=jvname]

]

[,VSPACE=(a[,b])]

[,VPWAIT=

TASK-STD num

]

Operand description

pathname catid userid filename stands for: [:catid:][$userid.]filename

Catalog ID of the pubset on which the file is stored.

Default value: the catalog ID assigned to the user ID (JOIN entry).

User ID to which the file is assigned.

Default value: user ID from the LOGON command.

Name of the cataloged file where the load module is located.

Names of file generations or file generations groups must not be specified here. If the file is not cataloged under the user’s

ID, it must be shareable (SHARE=YES operand in CAT command). The user ID must be specified.

U3586-J-Z125-7-7600

203

EXECUTE

CLASSII Concerns requests for additional memory pages for a program. A check is made as to whether the total number of pages requested

(including program space) exceeds the class 6 memory space available to you. In addition, the number of required pages resident in memory must not exceed the value allowed for current operation

(see the STATUS command, BIAS operand). The actual request for additionally required pages must be made in the program using the

REQM or REQMP macro; for resident memory pages, the CSTAT macro must also be specified (for macros, see the "Executive

Macros" manual [5]). The CLASSII operand is only effective in conjunction with the "pathname1" operand.

=(max,min,p) "max", "min", "p" are the number of resident and pageable memory pages required (in addition to the program size).

"max" is the number of additional resident memory pages essential for optimum program execution.

If these pages are not available, the value of "min" will be used for

"max".

"min" is the number of additional resident memory pages essential for program execution.

If these pages are not available, the program will not be loaded. In batch mode, the task is assigned to the queue for memory saturation (task type T1/HO; see the STATUS command).

"p" is the number of pageable memory pages required in addition to the program size.

ELEMENT Identifies a C-type member in the PL. The member identifier consists of the name of the member version

Specification of the version is optional. For a detailed description, see the "LMS" manual [14].

204

U3586-J-Z125-7-7600

EXECUTE

IDA

=YES

=NO

LIBRARY

=pathname

Allows the use of symbolic addresses for debugging programs with the aid of IDA commands, provided that an internal symbol dictionary exists for the program at that time.

You can have this internal symbol dictionary created by entering the corresponding operand in the COMOPT statement; e.g. "*COMOPT

ISD" for the assembler.

When calling the static loader ELDE, you must initiate the linking of the internal symbol dictionary by specifying IDA=Y for linking with

TSOSLNK (see the "Linkage Editor and Loaders" manual [22]).

The internal symbol dictionary is used.

The internal symbol dictionary is ignored; default value

Specifies a program library (PL) containing the load module as a C-type member.

MONJV

=jvname

SYMTEST

=ALL

=NO

Specifies a job variable which serves to monitor the program run.

The operating system enters the program’s processing state in the job variable ($R, $T, $A job initiated, job terminated normally, job terminated abnormally). The STATUS MONJV=... command, for example, could then be used to check this state. Note that the job variable must be cataloged before /EXECUTE ... is issued. For information about job variables please refer to the "Job Variables" manual [11]. Job variables cannot be used unless the JV software product is installed.

Name of the job variable.

The operand is required for debugging with AID.

SYMTEST=ALL allows the use of symbolic addresses for debugging programs with AID commands. This requires that a local or internal symbol dictionary be generated at program compilation time.

The symbolic address table or internal symbol dictionary is ignored; default value.

U3586-J-Z125-7-7600

205

EXECUTE

TIME Defines a maximum CPU time for the program run. The resulting behavior is different in interactive and batch mode:

Interactive mode:

After the specified time has expired, the program is interrupted and a user prompt asks whether you require a program dump. If you do not require a program dump, you can continue the program run or abort. The time specified with TIME=... is not compared with that of the LOGON command. If TIME=... is not specified, the program run is not interrupted - irrespective of the time specification, if any, in the LOGON command.

Batch mode:

The program run is aborted once the specified time has expired.

The program is not loaded if the specified time exceeds the CPU time still available for the task at that moment (ENTER-JOB-

Time specification is seconds; 0 t 32767.

VERSION

=version

=*STD

Version entry (supplements the member name).

Version identifier (up to 24 characters).

Latest version; default value.

VPSPACE=(a[,b]) Only permitted for vector-based computers; specifies the required vector storage space above ("a") or below ("b") the 16 Mb boundary.

"a" and "b" are integers.

VPWAIT Only permitted for vector-based computers; defines the maximum waiting time (in minutes) that may be used by the job for the reservation of storage space.

=TASK-STD

=num

The command is rejected in interactive mode if the reservation of vector storage space is not possible.

There is no restriction on the waiting time in batch mode.

Specifies the waiting time in minutes.

206

U3586-J-Z125-7-7600

EXECUTE

Examples

Example 1

Fig. EXEC-1 Load and start program

U3586-J-Z125-7-7600

207

EXECUTE

Example 2

If the EXECUTE command is used to load and start load modules which require resident space, operand CLASSII must be specified. In interactive mode, the user can use the "STATUS BIAS" command to check in advance whether the system has sufficient space for resident programs (CORE is displayed).

/EXECUTE PROG.RES.2,CLASSII=(5,2,10) (01)

(01) The program PROG-RES.2 requires a total of 10 virtual pages, at least 2 of which must be resident. Up to 5 pages can be made resident.

Example 3

(IN)

(OUT)

(IN)

(OUT)

(IN)

EXEC $EDOR,TIME=1

E D O R : FILE-EDITOR (V8.3D22)

% IDA0N51 PROGRAM INTERRUPT AT LOCATION ’00F3CA08 (EDOR), (CDUMP), EC=80’

% IDA0N45 DUMP DESIRED? REPLY (Y=USER-/AREADUMP;Y,SYSTEM=SYSTEMDUMP; N=NO)?

% EXC0075 TIME LIMIT FOR PROGRAM RUN EXCEEDED. PROGRAM TO BE CONTINUED? REPLY (Y=YES; N=NO)?

After 1 second of CPU time has elapsed (operand "TIME=1") the program is interrupted. If no dump is requested and the user responds "Y" to the inquiry regarding program continuation, the program will resume.

For further examples, see LOAD, PARAMETER and SYSFILE commands.

208

U3586-J-Z125-7-7600

FILE

FILE Define file attributes / control file processing

(see "Processing of catalog entries" on page 209).

Command description

The FILE command processes permanent and temporary files (but not EAM files) and file generations. It can be used to create new files and catalog entries, to change file attributes, and to import files from private volumes.

The following pages illustrate the various features of the FILE command with the help of a summary table and a diagram.

Unlike the CATALOG command, the FILE command cannot be used to define or change file attributes such as passwords or the access type (with the exception of the retention period). If a catalog entry is created using FILE, the system default values are used for these attributes. They can then be changed by means of a CATALOG command.

The FILE command establishes a connection between the program and the file via the task file table (TFT, see below).

Processing the catalog entry

If the file or file generation specified in the FILE command is not yet cataloged, a catalog entry is created under the user ID of the current job. The values entered for the operands DEVICE, VOLUME, SPACE, DDEVICE, DVOLUME, DSPACE and FSEQ (if applicable) are evaluated and transferred to the catalog entry; the values specified for other operands are only evaluated and transferred to the TFT entry if a file link name

(see below) is specified by means of the LINK operand (exception: MOUNT, TVSN and

STATE=FOREIGN).

If a file/file generation which is to be cataloged is stored on private disk, DMS takes the values for the catalog entry from the F1 label of the first volume containing the file.

U3586-J-Z125-7-7600

209

FILE

Task File Table (TFT)

The Task File Table (TFT) is a job-related table which establishes the connection between a physical file and a program. It consists of entries containing information on the file attributes and volumes. This information is taken into account during file processing. A TFT entry is accessed via its file link name.

If a link name for a file is specified by means of the LINK operand in the FILE command, the operating system creates an entry with this name in the TFT of the job and transfers to this entry all the values specified in the FILE command, including any

NULL operands (see below). A value specified in the TFT entry is given precedence over a value in the FCB. If neither the TFT entry nor the FCB contains a value, or if the

FILE command was specified with a NULL operand, then the value from the catalog or, if a new file is created, the appropriate default value is used.

When the file is opened, these values are transferred to the file control block (FCB).

When the file is closed, the catalog entry is updated with the values from the file control block.

Tape Set Table (TST)

The TST is a job-related table which, in conjunction with the TFT (see above) establishes the connection between volumes and files. It consists of entries containing a list of volumes. These entries can be accessed via their names.

TST entries are created with

FILE ..., TSET=name

and released with

RELEASE linkname

T F T

...

LINK=link1

Name of TST entry = X

...

LINK=link2

Name of TST entry = X

...

LINK=link3

Name of TST entry = Y

...

Fig. FILE-1 Relationship between TFT and TST

T S T

210

U3586-J-Z125-7-7600

FILE

Pool link name / ISAM pools

With NK-ISAM, ISAM files are processed in ISAM pools. The connection between the user ISAM pool and the file is established via the pool link name, which is specified by means of the POOLLNK operand.

File attributes / volumes

The FILE command allows file attributes such as record length, block length, etc. to be defined. In addition, devices and volumes can be requested, and storage space assigned or released.

The operand description refers to special features and interaction between the various operands.

NULL operands

If the file/file generation specified in the FILE command already exists, the operands

FCBTYPE, RECFORM, RECSIZE, BLKSIZE, KEYLEN, KEYPOS, LOGLEN, VALLEN and

VALPROP may be specified as "NULL operands" together with a file link name. A NULL operand is an operand for which no value is specified in the command call. For example:

/FILE ...,LINK=name,FCBTYPE=,RECFORM=,...

The corresponding fields of the TFT entry then contain the character string "NULL" as their value (output after the RDTFT command). When the file is opened, the information for these file attributes is transferred from the catalog entry to the file control block

(FCB).

U3586-J-Z125-7-7600

211

FILE

Processing of ISAM files with separate index and data sections

ISAM files can be created with separate index and data sections on different private disks. Both sections of the file may be independently assigned devices, volumes, and storage space - using DEVICE, VOLUME, and SPACE for the index section, and

DDEVICE, DVOLUME, and DSPACE for the data section. The allocation of devices, volumes, and storage space is carried out according to the same principle; however, it must be noted that the entries for SPACE always refer to VOLUME and DEVICE, while those for DSPACE always refer to DVOLUME and DDEVICE. Only the disk device types valid under DEVICE are permitted as device types for DDEVICE. There is no default value for DSPACE when a file is created.

If the FILE command refers to a file that does not yet occupy storage space, then

DDEVICE, DVOLUME and DSPACE must always be specified together. In the case of files that already occupy storage space, DSPACE may also be specified without

DDEVICE and DVOLUME. Storage space can only be released for the entire file (with

SPACE); it cannot be released separately for the index and data section. Once an ISAM file has been created with a separate index and data section, the index and data blocks can no longer be copied to the same volume. The option to split an ISAM file in this way is available on private volumes only, not on public volumes.

With NK-ISAM, it is not necessary to separate the index section and the data section. A secondary allocation only affects the data section.

Processing tape files

When a tape file is created, unlike a disk file, it is cataloged by default as shareable

(SHARE=YES). However, you can use the CATALOG command to change the file attributes before creating it (OPEN OUTPUT/OUTIN). The modified file attributes are entered in the file labels before the file is opened.

If successive file generations within a group belong to the same MF/MV set,

DISP=REUSE must on no account be specified in the CATALOG command since this may cause file generations to be destroyed.

212

U3586-J-Z125-7-7600

FILE

Fig. FILE-2 Functions of the FILE command

U3586-J-Z125-7-7600

213

FILE

Function overview of the FILE command

1. Naming and cataloging files, defining link names

Operand pathname

*DUMMY

LINK

POOLLNK

STATE

Operand value name name

FOREIGN

Function

- Create a catalog entry

- Allocate storage space for disk files

(primary allocation)

- Name the file/catalog entry to which subsequent operands will refer

Define a dummy file

(primarily for test purposes)

Define a file link name, for which a TFT entry is created

For NK-ISAM files: define a pool link name for the user ISAM pool

Import a non-cataloged file from private volumes

2. Defining file attributes

Operand

FCBTYPE

BLKCTRL

Operand value

ISAM/PAM/SAM/

BTAM

PAMKEY

Function

Access method for the file

DATA

File format "PAMKEY": block control information is entered in a key field separate from the PAM block

The block control field is located at the start of the PAM block

No block control information (converted to BLKCTRL=DATA for ISAM and SAM)

214

U3586-J-Z125-7-7600

RECSIZE

BLKSIZE

KEYPOS

KEYLEN

LOGLEN

VALLEN

CODE

Operand

RECFORM

FILE

Operand value

N/M/A length r

(STD,number) length number number number number

EBCDIC/ISO7/

OWN

Function

File with "variable" length records; the maximum record length is defined with RECSIZE

File with "fixed" length records; the record length is specified with RECSIZE

Record with "undefined" length records; the length of each record is entered in a register; each data block contains one, and only one, record

Specifies whether printer control characters are to be taken into account at specific positions

Record length for RECFORM=F/V

Block size as a multiple of the standard

PAM block

Tape files: block size for non-standard blocks

ISAM files: start position of the primary key in the data record

ISAM files: length of the primary key

ISAM files: length of the logical flag in the ISAM index

ISAM files: length of the value flag in the ISAM index

Tape files: code with which the file was created

U3586-J-Z125-7-7600

215

FILE

Operand

DEVICE

VOLUME

MOUNT

DDEVICE

DVOLUME

3. Requesting devices and volumes

FSEQ

VSEQ

TSET

TVSN

Operand value device

WORK

(PRIVATE,n)

(vsn,...)

(number,...) device

(vsn,...)

(PRIVATE,n)

Function

Define device type

Request work tape

Request private volumes

Define volume list

Mount request for private volumes

K-ISAM files only: define volume type for data section

K-ISAM files only: define private disk(s) for data section

Request, at the console, for n volumes to be mounted

UNK

NEW number

For tape files, when several files are on a single tape

The file position within a file set is unknown

The file is added to the file set

Position of the file in the file set number

For tape files that extend over multiple tapes designates the n-th tape plus all following tapes within the volume list

L=(number,...) Specifies the desired file section, i.e. the n-th tape of the volume list

(name,vsn) Tape files: defines a tape set for extending files or file sets

(vsn,...) Tape files: specifies which tapes from the tape set are required for current processing

216

U3586-J-Z125-7-7600

SHARUPD

CLOSMSG

WRCHK

OVERLAP

PAD

DUPEKY

4. Open mode and processing attributes

Operand

OPEN

VALPROP

WROUT

LABEL

TPMARK

DESTOC

Operand value Function

INPUT/OUTPUT/

EXTEND/INOUT/

OUTIN/UPDATE/

SINOUT/REVERSE

Specifies the OPEN mode for the file

NO/YES

NO/YES number

NO/YES

(STD,number)

NSTD

YES/NO

NO/YES

PAM or ISAM files: shared-update processing permitted or not permitted

SAM files: output of a message after completion of CLOSE processing

Disk files: read-after-write check

ISAM files: overlapped processing with regard to the I/O buffer

ISAM files: free space in data blocks during sequential file creation

ISAM files: Specifies whether or not the same key value may occur in a number of records

K-ISAM files: controls the evaluation of the value flags in a block for the key entry of the next higher level

ISAM files: write updated blocks immediately

Tape files: file with standard labels

(as per DIN 66029)

Tape file without labels

Tape file with non-standard labels

Tape files: write tape marks

Tape files: "destruction" of remaining data on tape

FILE

U3586-J-Z125-7-7600

217

FILE

Operand

TRANS

BUFOFF

TAPEWR

CHAINIO

BLIM

WRCPT

SECLEV

RETPD

BYPASS

Operand value

YES/NO

L/length

DEVICE-BUFFER

IMMEDIATE number number

HIGH/LOW days

LP/(LP,[;-]n)

Function

Tape files: convert non-EBCDIC tape files

Tape files: length of buffer offset within the data block

Files on tape cartridges: buffered processing

Unbuffered processing

Tape files: chained input/output

Tape files: automatic tape changing and checkpointing for n blocks

Tape files: write checkpoint

Tape files: ignore file protection attributes under specific conditions

(TPIGNORE attribute in the JOIN entry)

File protection for the specified period

Tape files: bypass label checking for input files (authorized users)

218

U3586-J-Z125-7-7600

FILE

5. Space management for disk files

Operand

SPACE

DSPACE

Operand value primary secondary

(page,number,

ABS) same as SPACE

Function

Primary allocation: space allocation takes immediate effect primary > 0: storage space is reserved primary < 0: storage space is released primary = 0: no storage space is reserved; only a catalog entry is created

Secondary allocation: space allocation is extended as required

Files on private disks: absolute allocation; "page" is the position of the file extent, "number" the number of PAM pages reserved

ISAM files: space management for the data section of files on private disk, if the index and data sections are separated

(see SPACE; space allocation only refers to the data section of the ISAM file - for space allocation for the index section, the SPACE operand must be used)

U3586-J-Z125-7-7600

219

FILE

Format and operand description

Operation

FILE

Operands

[ pathname

][,LINK=name][,POOLLNK=name][,STATE=FOREIGN]

*DUMMY

[,DEVICE = device

WORK

][,VOL[UME]=

PRIVATE

(PRIVATE,n) vsn

(vsn,...)

][,MOUNT= number

(number,..)

] primary

[,SPACE= (primary[,secondary]) ]

(page,number,ABS)

INPUT

EXTEND

INOUT

[,OPEN= OUTIN

OUTPUT

REVERSE

SINOUT

ISAM PAMKEY

][,FCBTYPE= BTAM ][,BLKCTRL= DATA

PAM

SAM

NO NO

[,RETPD=days][,SHARUPD= ][,CLOSMSG=

]

][,WRCHK=

YES YES

YES

]

[RECFORM=

V N

( F [, M ])

U A

][,RECSIZE= length reg

STD

][,BLKSIZE= (STD,n) ] length

[,KEYPOS=number][,KEYLEN=length][,DUPEKY= ]

YES

[,LOGLEN=length][,VALLEN=length][,VALPROP=

MIN

MAX

]

[,OVERLAP=

YES

][,PAD=number][,WROUT=

YES

]

220

U3586-J-Z125-7-7600

FILE

Operation

FILE

(cont.)

Operands

[,DDEVICE=device][,DVOLUME=

PRIVATE

(PRIVATE,n) primary

][,DSPACE= (primary[,secondary]) ]

(page,number,ABS) (vsn,...)

(vsn,...)

(STD,3)

STD

[,LABEL= (STD,number) ][,TPMARK=

NSTD

YES

][,DESTOC=

YES

]

EBCDIC

[,CODE= ISO7

OWN

][,TRANS=

YES

]

UNK

[,FSEQ= NEW number

][,VSEQ= number

(L=(number,...))

]

[,TSET= name

(name,vsn)

][,TVSN= vsn

(vsn,...)

]

[,BUFOFF= length

][,TAPEWR=

DEVICE-BUFFER

IMMEDIATE

][,CHAINIO=number]

[,BLIM=number][,

CHKPT

{NO }

ANY

BLIM

FEOV

ACTIVE

DUMMY

)]

[,SECLEV=

HIGH

LOW

HIGH

(

LOW

,OPR)

][,BYPASS= n

(LP, +n )

-n

]

The default values for the operands are interpreted and entered in the TFT entry only in conjunction with the LINK operand. They are not valid unless neither the corresponding field in the FCB nor the one in the TFT has been supplied with a value.

U3586-J-Z125-7-7600

221

FILE

pathname catid userid filename

*DUMMY stands for [:catid:][$userid.]filename

Designates the file or file generation to which this FILE command refers; "pathname" must not be a file generation group. If "pathname" is not yet cataloged, a catalog entry is created and the space specified for the primary allocation (see SPACE, below) is allocated.

Catalog ID of the pubset on which the file is stored. Default value: the catalog ID associated with the user ID (taken from the JOIN entry).

User ID of the file.

Default value: user ID specified in the LOGON command.

If the specified user ID differs from the one in the LOGON command, "pathname" must already be cataloged as shareable.

Otherwise, the FILE command will be rejected.

Fully-qualified name of a file or file generation.

Describes a dummy file. If the LINK operand is specified, a TFT entry with a volume list is created. If the TSET operand is also specified, a TSET entry is created in addition to the TFT entry. All other operands are simply checked for formal correctness but otherwise ignored, which means that neither devices nor volumes are requested, nor is storage space allocated, and no catalog entry is created.

Dummy files can, for example, be used for simulation of I/O operations during program testing or, for RESTART processing, replace files which are not actually needed for processing but are specified in the program.

Dummy file as an input file: when the program attempts to read from the file, EOF processing is initiated.

Dummy file as an output file: data is transferred to the I/O areas of the program, but output to a volume is suppressed.

222

U3586-J-Z125-7-7600

FILE

BLIM=number

BLKCTRL

Only for creating tape files with standard labels which are to be processed with the SAM access method and extend over several tapes. This means that "pathname" must not yet be cataloged, and the following operands must be specified in the FILE command:

FCBTYPE=SAM, OPEN=OUTPUT, LABEL=(STD,n),

VOLUME=(vsn,...).

"number" specifies how many data blocks may be written to one tape, where 1 number 999999. When this limit is reached, a tape swap is initiated (EOV processing). If requested with the CHKPT operand, a checkpoint is written to the end of the tape before EOV processing is started. If the end of the tape is reached before the specified number of blocks has been written, the user receives an error message in the FCB.

Defines the file format (see also the manual "DMS Introductory Guide and Command Interface" [8]).

Default values:

Volume with PAMKEY:

Volume without PAMKEY:

SAM/ISAM files:

UPAM files:

BLKCTRL=PAMKEY;

BLKCTRL=DATA;

BLKCTRL=NO.

BLKCTRL can also be specified as a NULL operand, in which case the BLKCTRL information from the catalog entry of the file is taken over when the file is opened.

U3586-J-Z125-7-7600

223

FILE

The table below shows the interaction of the BLKCTRL operand and the operands for ISAM file processing.

=PAMKEY

=DATA

=NO

Operand

POOLLNK

PAD

DUPEKY

WROUT

SHARUPD

VALPROP

DDEVICE

DVOLUME

DSPACE

= PAMKEY

No ISAM pools for

K-ISAM files

Minimum value for free space in data block

BLKCTRL

= DATA / NO

Connects the file to a user ISAM pool (otherwise: standard ISAM pool)

Maximum space to be left free in each data block

Default value depends on SHARUPD

Block locks

Value flag is evaluated for index entry

Index and data stored and managed separately on private disks

Records with duplicate keys have a time stamp added internally

Default value depends on SHARUPD and ISAM pool

Record or range locks

Value flag is ignored

Separation of index and data sections not supported

K file; the file format is "key-specific", i.e. the system stores control information in the PAMKEY, provided the volume allows the PAMKEY to be recorded.

NK file; the file format is "no-key", i.e. the system does not store control information in the PAMKEY but at the beginning of every logical block (in the case of ISAM files at the beginning of every 2-K block).

NK file; the file format is "no-key", i.e. the system does not store control information in the PAMKEY. This file format is for UPAM files only. SAM and ISAM files are processed as described for

BLKCTRL=DATA.

224

U3586-J-Z125-7-7600

BLKSIZE

=STD

=(STD,n)

=length

FILE

Specifies the blocking factor (for K files) or the length of a logical block/data block (for NK files), i.e. the length of the data transfer unit between the I/O devices.

The BLKSIZE specification is always interpreted and shown as

BLKTYPE and BLKSIZE in the output of the FSTAT command.

For disk files, there is interaction between this operand and the

SPACE and RECSIZE operands; for tape files, between this operand and the LABEL operand.

In the case of disk files/tape files with standard blocks, data blocks may consist of several PAM pages. The system automatically links together the PAM pages belonging to one transfer unit.

For tape files with non-standard blocks, the block format is not the same as that used by PPAM; a data block is defined as the number of bytes which are read or written in one read or write operation.

The file consists of standard PAM pages; default value. The data block and the PAM page are identical. The usable length of the standard block depends on the BLKCTRL specification (or on the disk type). Standard block lengths are:

BLKCTRL

= PAMKEY

= DATA

= NO

PAM page and usable length

2048-byte PAM page + 16-byte PAM key

2048-byte PAM page - 16-byte block control field

2032 bytes usable block length

2048-byte PAM page = usable block length

For K files: "n" is the blocking factor (1 n 16): each data block consists of n PAM pages, which means that the maximum block size is 16 PAM pages = 32768 bytes.

For NK files: the length of the logical block is n * 2048.

Only for tape files: specifies the block length in bytes and, at the same time, specifies that the file consists of non-standard blocks, i.e.

other than PAM pages.

When specifying "length", the user must consider, on the one hand, the settings of BUFOFF and RECFORM and, on the other hand, the settings FCBTYPE and CHAINIO.

U3586-J-Z125-7-7600

225

FILE

BUFOFF

Relationship between block length and record format:

Operand

RECFORM

RECFORM=F

Effects

RECFORM=V/U

"length" specifies the block size including the length of any buffer offset (see the BUFOFF operand). All blocks are the same size.

"length" specifies the maximum block size including the length of any buffer offset (see the BUFOFF operand). The block size, just like the record length, is variable.

If RECFORM=V is used together with CODE=EBCDIC or

LABEL=(STD,n) (n>1), "length" must be less than

100000

Relationship between access method and block length:

Operand

FCBTYPE

SAM/BTAM

PAM

Permissible values for "length"

1 n 32768

Only for tape files with BLKCTRL=DATA or SAM tape files without standard blocking. Defines the buffer offset, i.e. the length of a field which is inserted at the beginning of each data block.

Default value for tape files with BLKCTRL=DATA: for FCBTYPE=SAM: BUFOFF=16; for FCBTYPE SAM:

BUFOFF=12.

Default value for SAM tape files without standard blocking: for RECFORM=V: for RECFORM=F:

BUFOFF=4;

BUFOFF=0.

Buffer offset is permissible only together with RECFORM=V/F or

LABEL=(STD,2)/(STD,3). If neither of these is specified, the specification of BUFOFF will lead to an error.

226

U3586-J-Z125-7-7600

=length

BYPASS

=LP

=(LP,n)

=(LP,+n)

FILE

The BUFOFF value is taken from the HDR2 label of the file. If there is no HDR2 label, or if the "buffer offset" field contains blanks

(X’4040’), the default value is used.

Specifies the length of the buffer offset.

For SAM files with RECFORM=V: 0 length 4; if BUFOFF=4, the initial field contains the length of the current block; in the case of files with BLKCTRL=DATA, it contains the block control field.

BUFOFF can also be specified as a NULL operand, in which case the BUFOFF information from the catalog entry of the file is taken over when the file is opened.

Only for input files on tape. If permitted by the JOIN entry for your user ID, you can bypass the label checking routines and specify how the tape is to be positioned. DMS checks that the correct tape is mounted and activates any user routines for label handling in the normal manner. The positioning specification is evaluated only if no

OPENV exit is defined.

In addition to label checking, code checking is also bypassed. If

CODE=OWN is specified, the user must provide appropriate code tables of his own.

BYPASS permits the processing of tapes created under other operating systems (such as BS1000) or of tapes whose structure and label formats are not known to the system. The BYPASS specification is valid only during file processing; it is not included in the catalog entry for the file.

If specified together with BYPASS, the FSEQ operand is not evaluated.

Label handling is not executed. The header labels are neither checked nor read. The tape position is not changed.

0 n 32767. Labels are not handled. When the file is opened, the tape is positioned to the nth tape mark from the beginning of the tape.

(LP,0): the tape is positioned to the beginning of the tape.

0 n 127. Labels are not handled. When the file is opened, the tape is advanced by n tape marks from its current position.

(LP,+0): the tape is not repositioned.

U3586-J-Z125-7-7600

227

FILE

228

=(LP,-n) 0 n 127. Labels are not handled. When the file is opened, the tape is repositioned by n tape marks from its current position.

(LP,-0): the tape is not repositioned.

CHAINIO=number

Only for BTAM files with chained I/O. 1 number 16; "number" is the chaining factor which defines the length of the transport/transfer unit for input and output. "number" is a number of physical blocks, which means that the length of the transport unit is "number" *

BLKSIZE.

Although "number" can be overwritten by specifications in the program when processing BTAM files, CHAINIO=number must still be specified if chained I/O is to be used.

CHKPT

=(NO,)

=(BLIM,)

=(FEOV,)

=(ANY,)

For tape files: controls whether and when a checkpoint is to be written automatically at the end of the tape or how file processing is to continue after a restart (RESTART command).

Default value: CHKPT=(NO,ACTIVE)

No checkpoints are written automatically.

When the block limit specified by the BLIM operand is reached, a checkpoint is written automatically; the BLIM operand must be specified.

A checkpoint is written automatically each time the FEOV macro is called in an Assembler program.

A checkpoint is written automatically when the BLIM limit is reached or when the FEOV macro is called in an Assembler program. The

BLIM operand must be specified.

=(NO,DUMMY)

"pathname" is treated like a dummy file in the case of a restart using the RESTART command.

=(...,ACTIVE)

CLOSMSG

The file "pathname" is processed further in the case of a restart using the RESTART command.

For files to be processed sequentially (SAM): you can specify that a message is to be issued to SYSOUT on completion of CLOSE processing.

Default value: for disk files: CLOSMSG = NO

U3586-J-Z125-7-7600

FILE

=NO

=YES

CODE for tape files: CLOSMSG = YES

The close message is suppressed.

The close message is issued.

For SAM and BTAM tape files: specifies whether code translation tables are to be used during input/output.

For CODE=EBCDIC and CODE=ISO7 the German and international character sets are encoded in the same manner.

For CODE=ISO7/OWN and FCBTYPE=SAM, the following should be noted: the block size must be specified with BLKSIZE=length, so that no PAM keys are written; for outputs in locate mode (see the manual "DMS Introductory

Guide and Command Interface" [8]) with variable-length records

(RECFORM=V), the contents of the record length field change.

CODE can also be specified as a NULL operand, in which case the

CODE information from the catalog entry of the file will be taken over when the file is opened.

No code conversion during processing is necessary; default value.

=EBCDIC

=ISO7

=OWN

The tape file is written in ISO 7-bit code, which means that EBCDIC code is converted to ISO 7-bit code for output and vice versa for input.

Conversion is carried out with code tables provided by the user. The addresses of these tables must be in the file control block. At the same time, label processing must either be deactivated with

LABEL=NO or it must be carried out in the user program with

LABEL=NSTD.

DDEVICE=device For K-ISAM files with index and data sections stored on different private disks: DDEVICE designates the disk type for the data section

(that for the index section is specified with DEVICE); permissible entries for "device" can be found in the device table in the appendix.

DDEVICE must be specified if no storage space has yet been reserved for the file.

U3586-J-Z125-7-7600

229

FILE

DESTOC

=NO

=YES

DEVICE

=device

=WORK

For tape processing: defines whether any remaining data on the tape is to be erased by overwriting on completion of EOF/EOV processing.

DESTOC is only effective if a TFT entry is also created for

"pathname" by means of the LINK operand.

The DESTOC specification has the same function as the DESTROY operand in the CATALOG command. However, DESTOC overrides the entry in the DESTROY field of the catalog entry. If DESTOC is omitted in the FILE command, the specification from the catalog entry is used.

Data on the remainder of the tape is not deleted.

After the EOF labels have been written, the data on the remainder of the tape is erased.

For files on private volumes: defines the device type for the volume

(disk/tape) or, in the case of tape processing, requests a work tape.

Default value: If neither DEVICE nor VOLUME is specified, and a new file is to be created, the file will be created on public disk; otherwise, in the case of an existing file, the volume type in the catalog entry is used.

Specifies the type of volume; permissible entries for "device" in the case of tape or disk devices can be found in the device list in the appendix.

If, when a file is created, a tape device is specified for DEVICE, but no VOLUME is indicated, a free tape with standard labels will be requested and assigned to the operator when the file is opened. A free tape is a tape on which nothing has yet been written or any tape for which the retention period of the first file on the tape has expired, so that write access is permitted.

Only for tape processing: requests a work tape. Such tapes are not assigned to owners (their VOL1 labels contain only blanks, i.e. X’40’) and are automatically released at the end of the job. It is therefore not possible to protect and archive files on a work tape.

If DEVICE=WORK is specified, any entries for the VOLUME operand are ignored. The operands STATE=FOREIGN and TSET must not be specified together with DEVICE=WORK.

230

U3586-J-Z125-7-7600

FILE

DSPACE

DEVICE=WORK should not be specified for multivolume files, since any available work tape is automatically assigned.

Magnetic tape cartridges cannot be requested as work tapes.

Defines the space allocations for the data section of a K-ISAM file

(for K-ISAM files whose index and data sections are stored on different private disks). The conventions for primary, secondary and absolute allocation are the the same as those for the SPACE operand. However, the entries refer to the volume(s) specified in the

DVOLUME operand (see also the DDEVICE and DVOLUME operands).

=primary Primary allocation; effective immediately.

0 primary 50331645

=(primary,secondary)

Primary allocation, which is effective immediately, and secondary allocation, which is transferred to the catalog entry.

0 secondary 32767

=(page,number,ABS) page: number:

ABS: number of the PAM page at which the allocation begins; number of PAM pages to be allocated; absolute allocation.

DUPEKY

=NO

=YES

For ISAM files; specifies whether duplicate ISAM keys may be used.

DUPEKY is only significant if the file is to be processed with the PUT or STORE macro (See "DMS Assembler Interface" manual [9] and

"Executive Macros" manual [5]).

Duplicate ISAM keys are not permitted; default value.

Duplicate ISAM keys are permitted. Records that have the same

ISAM key do not overwrite each other, but are written sequentially in the order in which they are created.

In NK-ISAM, an 8-byte time stamp is appended internally to records with duplicate primary keys. This must be taken into account when the record length is defined. "Secondary" keys may also be defined in which case no duplicate primary keys may be used.

U3586-J-Z125-7-7600

231

FILE

DVOLUME

=vsn

=(vsn,...)

=PRIVATE

=(PRIVATE,n)

For K-ISAM files with index and data sections stored on different private disks; specifies the volume serial number ("vsn") of the volume on which the data section of the ISAM file is to be stored.

The operand VOLUME must be specified for the index section.

The specified private disk is requested for the data section of the

ISAM file.

Several private disks, whose VSNs are listed, are requested. A maximum of 255 VSNs may be specified.

Requests a private volume at the console.

FCBTYPE

=ISAM

=BTAM

=PAM

=SAM

1 n 9; requests "n" private volumes at the console.

Specifies the access method to be used for file processing.

FCBTYPE can also be specified as a NULL operand, in which case the FCBTYPE information from the catalog entry of the file will be transferred when the file is opened.

"pathname" is an ISAM file; default value.

Depending on the value of the BLKCTRL operand, it is processed as an NK-ISAM file (BLKCTRL=DATA) or as a K-ISAM file

(BLKCTRL=PAMKEY).

ISAM-specific operands: DUPEKY, KEYLEN, KEYPOS, LOGLEN,

VALLEN, WROUT and DDEVICE, DSPACE, DVOLUME and

VALPROP.

"pathname" is a tape file which is to be processed using access method BTAM. BTAM processing is not supported by all programming languages.

BTAM-specific operands: CHAINIO, OPEN=SINOUT

"pathname" is a PAM file that is processed using access method

UPAM. PAM files may be stored on tape or disk.

"pathname" is a SAM file on disk or tape. SAM files are generally processed sequentially using either of the access methods SAM or

UPAM.

SAM-specific operands: BUFOFF, CLOSMSG, OPEN=UPDATE

232

U3586-J-Z125-7-7600

FILE

FSEQ

=UNK

=NEW

For tape files which belong to a file set: specifies the (sequential) number of a file within the file set. If, for example, several files with the same name are stored on one tape, access to a specific file is controlled by means of FSEQ. This also applies to MF/MV sets.

Default value: FSEQ = 1

FSEQ can also be specified as a NULL operand, in which case the

FSEQ information from the catalog entry of the file will be taken over when the file is opened.

Permissible only for files with standard labels: The start position of the file is unknown.

Permissible only for files which are not yet cataloged: The file

"pathname" is to be added to a file set.

The file pointer is positioned to the end of the file set, and the new file is written behind the currently last file of the file set. The "file sequence number" is incremented by 1.

=number Specifies the file sequence number of "pathname" within the file set, where 0 number 9999.

FSEQ=0, just like FSEQ=1, denotes the first file of the file set.

If "pathname" is already cataloged, "number" must be the same as the file sequence number in the catalog entry. If a new file is to be created, it is added to the end of the file set, which means that its file sequence number must be 1 higher than that of the "old" last file in the file set. "number" is transferred to the catalog entry (even in conjunction with STATE=FOREIGN).

KEYLEN=length For ISAM files; specifies the length of the ISAM primary key in bytes, where 1 length 255.

Default value: KEYLEN = 8

KEYLEN can also be specified as a NULL operand, in which case the KEYLEN information from the catalog entry of the file will be taken over when the file is opened.

U3586-J-Z125-7-7600

233

FILE

KEYPOS=number For ISAM files; specifies the position of the ISAM primary key in the record. In variable-length records, 4 bytes for the record length and control field must be taken into account. The ISAM primary key may be anywhere in the record, but must be in the same position in each record of one and the same file.

Default value: for files with RECFORM=V: KEYPOS=5 for files with RECFORM=F: KEYPOS=1

KEYPOS can also be specified as a NULL operand, in which case the KEYPOS information from the catalog entry of the file will be taken over when the file is opened.

LABEL

=STD

Only for tape files; specifies the label type for files on tape or tape cartridge; the SECLEV operand determines how the labels are processed.

Default value: LABEL=(STD,3)

For existing tape files, the label standard version in the VOL1 label always applies. The LABEL operand is evaluated for output files

(OPEN OUTIN/OUTPUT). If the tape already contains files or file sections, the label standard version in the VOL1 label is set or updated as specified in the LABEL operand.

File and volume receive/have standard labels in accordance with

DIN 66029, interchange level 1.

=(STD,number)

File and volume receive/have standard labels in accordance with the

DIN 66029 interchange level designated by "number", where 0 number 3; interchange level 4 is in preparation.

234

U3586-J-Z125-7-7600

=NO

FILE

The following table illustrates the effects of the LABEL operand:

DIN 66029 interchange level/ date

Label standard version in

VOL1 label

CODE=ISO-7/OWN

(STD,0)

_ (blank) not permitted

(STD,1)

8/1972

(STD,2)

6/1976

STD,3)

3/1978

STD blocks converted to non-standard blocks

RECFORM=V: conversion to

D-format

RECSIZE > 9999 or

BLKSIZE > 9999

OPEN error

STD blocks converted to non-standard blocks

SAM only

STD blocks converted to non-standard blocks

CODE=EBCDIC

Access method

RECFORM=U

STD blocks converted to non-standard blocks

SAM only

Invalid for output files; converted to

(STD,2)

(STD,1) is used for:

RECFORM=V and CODE=EBCDIC

BLKSIZE=STD

FCBTYPE=PAM or FCBTYPE=BTAM

For (STD,0), CODE=EBCDIC must be used.

If the label standard version in the VOL1 label is less than

(STD,number), "number" assumes the value of the label standard version.

File labels are neither read nor written (no file label processing). If the tape has standard labels, the system processes the volume labels and checks the access rights.

U3586-J-Z125-7-7600

235

FILE

236

=NSTD

LOGLEN=length For K-ISAM files only; specifies the length (in bytes) of the logical flag in the ISAM index. The maximum length is determined by the length of the primary key and the length of any existing value flag

(see VALLEN, below). Since the entire ISAM index must not be longer than 255 bytes, the following rule applies:

length 255 - KEYLEN - VALLEN

Default value: LOGLEN=0, i.e. there is no logical flag in the

ISAM index.

In the ISAM index, the primary key may be followed by a logical flag in which selection criteria are defined bit-by-bit and encoded in binary code. All logical flags of a block are evaluated, and the result is placed in the next-higher index entry. The LOGLEN specification is ignored by NK-ISAM.

LOGLEN can also be specified as a NULL operand, in which case the LOGLEN information from the catalog entry of the file will be transferred when the file is opened.

LINK=name

The tape file already has or is to receive non-standard labels and file label processing is performed in the user program. If the volume has standard labels, the system processes these and checks the access authorization.

A link can be established dynamically in the TFT entry between a file and a processing program by means of the file link name. Here, a

TFT entry is to be created for the specified file link name ("name").

The other operands are then evaluated (incl. NULL operands) and their values are placed in this TFT entry (exception: SPACE operand).

If an entry of the same name already exists in the TFT, this entry is released and then recreated. The old device reservations are cancelled except for tape devices, which remain reserved for the job and may need to be released with the SECURE command. If the old

TFT entry was locked with the HOLD command, the new entry will be locked as well.

If the LINK operand is not specified, no TFT entry is created, as a result of which some of the specified operands cannot be interpreted

U3586-J-Z125-7-7600

MOUNT

FILE

"name" may be from 1-8 characters; permissible character set: letters, digits, special characters in accordance with the character set available for file names. The name must contain at least one letter or one special character; "." and "-" must not be specified next to each other; a period must not be used at the beginning of the name.

Determines whether or not the operator at the console should receive a request for the private volume(s) specified.

If "pathname" refers to a tape file, the operator at the console receives a request for the private volumes. The volume serial numbers are obtained from the volume list in the catalog entry and from the specifications in the VOLUME operand. This request is suppressed when MOUNT=0 is specified (see below).

If "pathname" refers to a disk file, the MOUNT operand is ignored.

Exception: MOUNT=0 (see below).

The default value is MOUNT=1, which causes the first volume in the volume list to be requested.

Interaction between MOUNT and other operands:

If DEVICE=WORK is specified at the same time, the MOUNT operand is ignored.

MOUNT values must not be less than those of VSEQ (exception:

MOUNT=0); if VSEQ=n, the MOUNT list must begin with "n":

(MOUNT=(n[,n+1][,n+2][,...])); if VSEQ=(L=(n1, n2,...)), the VSEQ and MOUNT lists must match

(MOUNT=(n1, n2,...)); the MOUNT list may contain fewer elements.

If VSEQ is omitted, the MOUNT list must begin with 1 and ascend without gaps.

If TSET and VOLUME are also specified for non-cataloged tape files, the operating system applies the MOUNT operand on the volume list in the TST entry.

If VOLUME is also specified for cataloged tape files, MOUNT refers to the volume list in the catalog entry and to the logically following list in the VOLUME operand; for non-cataloged tape files, MOUNT refers only to the list in the VOLUME operand.

U3586-J-Z125-7-7600

237

FILE

=number

=(number,...)

OPEN

If "pathname" refers to a disk file, the volume is not requested until the file is to be opened. "pathname" must exist and neither DEVICE,

VOLUME nor SPACE (or DDEVICE, DVOLUME, DSPACE) may be specified.

1 number 255 (number > 1 together with VSEQ only). This specification refers to the sequence of the volume serial numbers in the volume list. MOUNT=n causes the nth tape in the list to be requested and a tape device to be made available.

1 number 255 (number > 1 together with VSEQ only).

A number of volumes to be mounted can be requested in a list. The numbers in the list must be in ascending order. One tape device is then reserved for each volume specified in the list.

Specifies the OPEN mode for the file. This setting may be overwritten by the call to the OPEN macro in the program when the file is opened.

The following table shows which OPEN modes are permissible for the various access methods.

=INPUT

=EXTEND

OPEN mode

INPUT

EXTEND

INOUT

OUTIN

OUTPUT

REVERSE

SINOUT

UPDATE

ISAM x x

x x x

BTAM x x x x

x x x

SAM

x x

x x x

UPAM x

x x OPEN mode is permitted

OPEN mode is not permitted

The various OPEN modes are described in detail in the descriptions of the access methods.

"pathname" is an input file, i.e. it must exist; default value.

An existing file is extended, i.e. further data blocks are added to the end of the file or the file is overwritten from a certain position onwards; only sequential write operations are permitted. For tape files, the value in the LABEL operands determines whether or not labels are to be generated.

238

U3586-J-Z125-7-7600

FILE

=INOUT

=OUTIN

=OUTPUT

=REVERSE

=SINOUT

=UPDATE

OVERLAP

=NO

=YES

PAD=number

An existing file is opened for non-sequential processing; write and read operations are permitted. For tape files, the tape is positioned to the beginning of the tape after OPEN processing; no labels are written.

A file is created or, if it already exists, overwritten from the beginning. Both read and write operations are permitted (nonsequential). Labels are written for tape files.

A file is created or, if it already exists, overwritten from the beginning. Labels are created for tape files.

The file "pathname" must already exist and is used as an input file for sequential reading from end-of-file to beginning-of-file. The file must not extend over several volumes. For tape files, the tape is positioned to the end of the file after OPEN processing.

Only for tape files processed with the BTAM access method. The file must exist and the tape must not be positioned to the beginning of tape. Data blocks can be read or written; labels are not processed.

In contrast to INOUT, the tape is not positioned.

Only for SAM disk files; the file is to be processed in locate mode.

Only for ISAM files; if this is specified and a second I/O area is defined in the program (IOAREA2 in the FCB), read operations

(GET/GETR) can be executed in overlap mode.

Default value: depends on the BLKCTRL specification.

For NK-ISAM, "overlapped processing" means that contiguous blocks are also read into the ISAM pool. OVERLAP=YES should be used only when reading is primarily sequential.

Read operations are not to be executed in overlap mode.

Read operations are to be executed in overlap mode.

For sequentially created ISAM files; the "padding factor" PAD specifies how much free space is to be left in each data block for subsequent extension of the file (specified as a percentage of the block size defined with BLKSIZE). PAD thus has an effect on the block splitting rate when a file is extended non-sequentially.

0 number 99; default value: PAD = 15

The PAD specification has different effects for NK-ISAM and K-ISAM.

For NK-ISAM, the block is filled at least up to the PAD limit; for K-

ISAM, it is never filled above the PAD limit.

U3586-J-Z125-7-7600

239

FILE

240

POOLLNK=name Only for NK-ISAM files processed in ISAM pools (NK-ISAM); "name" is the "pool link name" (up to 8 characters long) which is entered in the TFT. (The ISAM pool is created by means of the CREATE-ISAM-

POOL command, and the pool link name is assigned to it using

ADD-ISAM-POOL-LINK.)

The valid character set for "name" corresponds to the one for file names: letters, digits, and the special characters "#" and "@".

RECFORM Specifies the record format of the file "pathname" and also specifies which control characters are to be interpreted if the file is sent to a printer.

Default value: RECFORM = (V,N)

The record format specification is evaluated only for the access methods SAM and ISAM. UPAM processes files only on a block-byblock basis; the specification for the RECFORM operand is ignored.

BTAM accepts a RECFORM specification. For the relationships between the RECFORM and RECSIZE specifications, see "RECSIZE".

For information on the interpretation of the print control characters, see the PRINT command (operand SPACE).

For tape files with RECFORM=V and CODE=EBCDIC or

LABEL=(STD,n), where (n > 1), the contents of the record length and block size fields are converted internally to the D format: the value for the record/block size is represented as a decimal number.

For such files, the block size must be less than 10000 bytes. During input, records with a D format are reconverted to hexadecimal format before they are transferred to the user area.

RECFORM can also be specified as a NULL operand, in which case the RECFORM information from the catalog entry of the file will be transferred when the file is opened.

"pathname" consists of variable-length records, which means that the user must bear in mind, when programming, that each record is preceded by a 4-byte field whose first two bytes contain the record length in binary form. Bytes 3 and 4 of this field are used by the system. For input files, the record length field is specified by the system; for output files, you must do this yourself. For BTAM files, the specification RECFORM=V is treated like RECFORM=U.

"pathname" consists of fixed-length records, i.e. the user does not need to take record length and control fields into account. All records in the file have the same length, which is defined via the

RECSIZE operand.

U3586-J-Z125-7-7600

=(...,N)

=(...,M)

=(...,A)

RECSIZE

=length

=reg

FILE

"pathname" consists of records with "undefined" length. Each data block contains one, and only one record, whose length is transferred to a register. The system sets this register for input and the user program sets it for output (see the BLKSIZE operand). RECFORM=U converts the specification LABEL=(STD,3) into (STD,2).

RECFORM=U is not permitted for ISAM files.

"pathname" is not a print file and therefore contains no print control characters. It should not be printed with control character evaluation.

The first data byte in each record is interpreted as a control character in EBCDIC code and the file can be printed with the specification SPACE=E in the PRINT command. For ISAM files, the

ISAM index is taken into account.

The first data byte in each record is interpreted as an ASA control character and the file can be printed with the specification

SPACE=A in the PRINT command.

Specifies the record length as a function of the specification in the

RECFORM operand.

RECSIZE can also be specified as a NULL operand, in which case the RECSIZE information from the catalog entry of the file will be taken over when the file is opened.

For RECFORM=F: the record length in bytes (all records in the file are the same length).

For RECFORM=V: The RECSIZE specification is ignored, unless an

ISAM file is being read in move mode. If "length" is smaller than the record to be read, only the specified "length" of the record is transferred, and error handling is initiated.

RECSIZE=0 means RECSIZE BLKSIZE.

For NK-ISAM files, it should be noted that overflow blocks may result if the maximum record length is fully utilized.

For tape files, the interaction with the operands CODE and LABEL should be noted: if CODE=EBCDIC or LABEL > 1, RECSIZE must be 9999 (international standard).

For RECFORM=U: the operand RECSIZE must specify a generalpurpose register (2 reg 12) which contains the current record length for input and output. The system sets this register for input and the user program must set it for output.

U3586-J-Z125-7-7600

241

FILE

RETPD=days

SECLEV

=HIGH

=LOW

=(...,OPR)

Defines a retention period for the file in days, i.e. a period during which the file may be read, but not updated or erased.

The RETPD operand is effective only if a TFT entry is created with the LINK operand and the file is then opened.

"days" specifies the length of the retention period in days (0..32767).

The date on which the retention period ends is computed by the system and noted in the EXDATE field of the catalog entry (see the

FSTATUS command).

Default value: days=0, i.e. the file may be updated or erased immediately.

The retention period can also be controlled by the CATALOG command (see the CATALOG command for details).

Only for tape files; the operand SECLEV (security level) refers to the

TPIGNORE entry in the JOIN entry of the user ID (see also the

SHOW-USER-ATTRIBUTES command). SECLEV specifications are ignored in interactive mode. In batch mode, if you have the appropriate authorization, you can use SECLEV to specify whether error messages are to be suppressed and/or whether additional label checking is to be executed.

In batch mode, error messages are sent to the system operator console. If the job is running under a user ID with TPIGNORE=YES in its JOIN entry, the operator may ignore the error messages.

Permissible only for the system administrator or the tape/file owner if TPIGNORE=YES is defined in the JOIN entry of the user ID: certain error messages are suppressed in batch mode.

The entry OPR (= overwrite protection) causes the system to execute additional label checking: if a file is written on a tape behind an existing file, the labels of the preceding file are checked; the expiration date of the new file must not be greater than that of the preceding file.

242

U3586-J-Z125-7-7600

SHARUPD

=NO

=YES

SPACE

FILE

Only for ISAM or UPAM disk files; specifies whether several jobs may concurrently open the file with an open mode other than OPEN

INPUT.

As soon as the file is opened by a job with OPEN INPUT, it is locked for all other jobs. Concurrent access to the file by several jobs is possible only if the file is used as an input file by all of these jobs, i.e. it is opened with OPEN INPUT. If the file has been opened with OPEN INPUT, any attempt to open it with another open mode is rejected; default value.

Only for ISAM and PAM files: the file can be processed concurrently by several jobs, provided SHARUPD=YES is specified in all of these jobs. With UPAM, data blocks can be protected against access by other jobs as long as processing takes place. For ISAM, these locks are set automatically by the system whenever necessary. With NK-

ISAM, the shared-update processing of files must be carried out in host-specific user ISAM pools. SHARUPD=YES simultaneously activates WROUT=YES for K-ISAM files (see the WROUT operand, below).

Only for disk files: controls, with the primary, secondary or absolute allocation, the storage space reserved for the file. The SPACE operand is always evaluated, even if the LINK operand is not concurrently specified.

Default value: the values defined for primary and secondary allocation during system generation

If you request more space in the pubset than is assigned to you in the JOIN entry (see the SHOW-USER-ATTRIBUTES command), the

FILE command is rejected. If you are authorized to use enforcement, the system informs you with a message before your free storage space assignment is exceeded

In the case of private disks, a partial allocation is made (whenever possible) if the request exceeds the amount of free storage space.

The command FILE ...,SPACE=... is rejected for files which are open or for which exclusive reservations have been made by a foreign task (with SECURE-RESOURCE-ALLOCATION, for example). File protection attributes, if any, are taken into account.

U3586-J-Z125-7-7600

243

FILE

In order to minimize the management overhead for the system, the following should be noted when primary and secondary allocations are defined: the primary allocation should match the estimated size of the file to be created; the secondary allocation should be between 9 and 15 PAM pages; for large files, the primary and secondary allocations should be multiples of the management units packet or segment (24 and

192 PAM pages, respectively).

Relationship with BLKSIZE: when defining "primary" and "secondary", the block size defined for the file should be taken into account; for

BLKSIZE=(STD,n) -- where n 2 -the following applies:

File type

SAM

K-ISAM

NK-ISAM

PAM (chained I/O)

"primary"

SPACE operand

"secondary"

2n + 1 n n

2n + 2

= n n

= n

244

U3586-J-Z125-7-7600

=primary

FILE

The primary allocation or release of PAM pages, which is immediately effective.

1 primary 50331645: storage space allocation; "primary" is rounded up to a multiple of 3 and the corresponding number of

PAM pages is allocated on the pubset or on the private disk specified in the VOLUME operand. When using the FILE command

(macro) in procedures (programs), please note that each FILE command with a positive primary allocation reserves space for the file. If the primary allocation is large, this will quickly exhaust the storage space assignment for the user ID.

-50331645 primary -1: storage space release after rounding

"primary" up to a multiple of 3.

Only the user ID from the LOGON command may be specified in order to release storage space.

The space is released from the end of the file, working backwards, as specified in the volume list (any specification in the VOLUME operand is ignored). Only "unused" units (1 unit = 3 PAM pages) are released. For ISAM files, the data and index sections cannot be released separately (see the DSPACE operand, above). In the case of files on private disks, at least 3 PAM pages remain allocated to the file, even if they are unused.

If a file has been cataloged with DESTROY=YES, all PAM pages that can be released are first overwritten with binary zeros. However, since units are not taken into account when the PAM pages are overwritten (contrary to when they are released), the file may be overwritten with binary zeros up to the end-of-file pointer.

If the file resides on private disks, these disks are requested and may need to be mounted.

primary=0: no change to the storage space reservation; permissible for files on private disks only if the the file already occupies storage space.

U3586-J-Z125-7-7600

245

FILE

246

=(primary,secondary)

Defines the primary and secondary allocations. In contrast to the primary allocation, the secondary allocation is not immediately effective when the FILE command is entered, but only when the reserved space becomes insufficient during creation or extension of the file. The secondary allocation value is transferred to the catalog entry (field 2ND ALLO; cf. FSTATUS output).

-50331645 primary 50331645: see "primary", above.

SPACE=(0,secondary) defines or changes the secondary allocation and transfers the (new) value to the catalog entry. This may be specified for files or file generations on private disk only if the file already occupies storage space.

secondary: the secondary allocation, i.e. the number of PAM pages by which the storage space is to be extended if this should become necessary.

1 secondary 32767: "secondary" is transferred unchanged to the catalog entry. It is not rounded up to a multiple of 3 until the secondary allocation comes into force.

secondary=0: prevents dynamic expansion of the file.

=(page,number,ABS)

Only for files on private disk: absolute allocation (only permitted when specified together with VOLUME=vsn). The requested space is assigned as a contiguous storage area. If there is not enough free space on the disk, the FILE command is rejected; no partial allocation is made. Since the absolute allocation always refers to one volume, a separate FILE command must be issued for each volume.

If the absolute allocation is the first space request for the file, the secondary allocation is set to 0.

"page" = the block number of the PAM page with which the space reservation is to start on the private disk. Since space is always allocated in units of 3 PAM pages, "page" must be 3n + 1 (where n

0).

The first PAM page on which storage space can be reserved on a disk depends on how the disk was formatted.

"number": specifies how many PAM pages are to be reserved on the volume (number 50331645). The value must be a multiple of 3. As the capacity of a given disk depends on the disk type and how it was formatted, the user should ask the system administrator what the maximum permissible value for "number" is.

U3586-J-Z125-7-7600

FILE

ABS: the keyword "ABS" identifies an absolute allocation.

STATE=FOREIGN For files on private volumes for which a system catalog entry is to be created (file import). For file generations, the group entry may also have to be reconstructed (with a CATALOG command/macro) before the generations can be imported. Files which are imported with STATE=FOREIGN should be exported from the catalog of their

"old" owner (with ERASE, CATALOG).

Files on private disk: only the first volume of a file needs to be mounted when the file is opened, because the system creates the catalog entry from information in the F1 label of the private disk.

Tape files: The VSNs of all tapes occupied by the file must be listed in the correct order in the VOLUME operand.

A "foreign" indicator is set in the catalog entry, so that it is initially not possible to change the file attributes with a CATALOG command.

This indicator is not reset until the file is opened.

If the foreign tape file has standard labels, the file attributes

RECFORM, RECSIZE, BLKSIZE and CODE are transferred from the

HDR2 label to the catalog entry when the file is opened. The file may be cataloged under more than one user ID; the system then ensures that the catalog entry and the label information are kept consistent.

If the foreign file has non-standard labels or no labels, you must specify the operands RECFORM, RECSIZE and BLKSIZE in the FILE command. If the file is cataloged under more than one user ID, each user is responsible for ensuring that consistency between the catalog entry and the label information is maintained.

The following prerequisites must be fulfilled for importing a foreign tape file: if you are not the file owner, the volume and the file must be shareable (indicators in the VOL1 and HDR1 labels): only the file owner may extend the file; if write protection is defined for the file, or if the retention period has not yet elapsed, the file owner must specify SECLEV=LOW in the FCB macro or FILE command/macro if the file is to be extended; if SECLEV=LOW is specified in FCB or FILE, any passwords which exist for the file are ignored.

U3586-J-Z125-7-7600

247

FILE

The method for importing foreign tape files is not the same as that used for private disk files. The reason for this is that the catalog entry for a foreign disk file is unique. For foreign tape files, this uniqueness could be achieved if the user IDs of the file owners already existed in the system into which the file is to be imported. If, however, these user IDs do not exist, it is not possible to change the owner identification on the tape (a hardware restriction would cause the file to be destroyed).

Even if the system administrator imports a file for an existing user ID, it cannot be guaranteed that the catalog entry will be unique, since the file can also be cataloged under another user ID.

Nevertheless, tape files with standard labels are protected just as well as disk files against conflicts between the file attributes specified in the labels and those in the catalog entry. This is achieved by the restrictions in the CATALOG command. The only risk factor is that the file owner may change the file attributes by specifying SECLEV=LOW in the FCB. For this reason, there should never be several catalog entries in one system for one file if the owner of the file also works in this system.

TAPEWR Only for files on tape cartridges. The user can specify whether or not output is to be buffered (input is always buffered).

=DEVICE-BUFFER

Output is buffered by the tape controller, thus achieving a high data transfer rate; default value.

=IMMEDIATE Output is not buffered.

TPMARK Only for tape files without standard labels (LABEL=NO/NSTD); specifies whether tape marks are to be written. Tape files with

LABEL=(STD,n) automatically receive tape marks after the labels.

=YES

=NO

Tape files with non-standard labels: the tape mark follows the label; default value.

Tape files without labels: the tape mark is written at the beginning of the tape.

No tape mark is written.

248

U3586-J-Z125-7-7600

TRANS

=YES

=NO

TSET

=name

FILE

Only for tape files used as input files and not created with

CODE=EBCDIC; specifies how the code of the file is to be converted during reading.

ISO 7-bit code or OWN code is converted into EBCDIC code; default value.

ISO 7-bit code is converted into 8-bit format by inserting a leading zero.

Only for target tape files, together with LINK=name; TSET (tape set) establishes the connection with an existing TST (tape set table) entry or creates a new TST entry, as required (see above "Tape Set Table

(TST)"). The corresponding TFT entry then points to this entry in the

TST.

TSET may be specified only for output files with standard labels. At the same time, a device type must be specified via the DEVICE operand (DEVICE=WORK is not permissible).

When the first file of a file set is created or a file set is extended, the only permitted value for FSEQ is FSEQ=1 or FSEQ=NEW, respectively.

If the specified name does not yet exist in any TST entry, a new TST entry with the file number 1 is created. The file set identifier set during OPEN corresponds to the identifier in the HDR1 label.

If a TST entry with the specified name already exists, the file number is incremented by 1 with each FILE command/macro (see also the

RELEASE command).

The volume list in the TST entry is updated on the basis of the information in the current FILE command.

The tape sequence is updated during OPEN processing.

When a TFT entry linked to a TST entry is deleted, the TST entry is not released unless the deleted TFT entry is the last entry linked with it.

4-character alphanumeric name which establishes the link with the

TST entry with this name or creates a new TST entry.

U3586-J-Z125-7-7600

249

FILE

=(name,vsn) 4-character alphanumeric name designating a TST entry. The volume serial number ("vsn") is the "file set identifier".

If the TST entry does not yet contain a file set identifier, the VSN is added to the TST; otherwise, the specified VSN must match that of the TST entry. When a file is opened, the file set identifiers in the

TST entry and in the HDR1 label must agree.

TVSN

=vsn

=(vsn,...)

Only for tape files used as input files; specifies which volumes are needed. If the TVSN operand is specified, the volume list in the catalog entry is ignored during file processing; only the volumes specified via TVSN are used. However, the catalog entry is not changed.

The TVSN operand must not be specified together with the VOLUME operand.

Volume serial number of the volume containing the file to be read.

List specifying up to 255 VSNs of volumes which contain the file to be read.

If "pathname" is a multivolume file, DMS assumes that the specified volume list matches the file section list in the VSEQ operand. It is up to you to ensure that the volume list begins with the volume containing the beginning of the file. If no VSEQ operand is specified, the system searches for the first file section when the file is opened and positions the tape to this section. After this, all file sections are loaded in the existing order.

VALLEN=length Only for K-ISAM files; specifies the length of the value flag in the

ISAM index. Value flags are evaluated block-by-block and transferred to the next higher index entry as specified in the VALPROP operand.

VALLEN can also be specified as a NULL operand, in which case the VALLEN information from the catalog entry of the file will be taken over when the file is opened.

Default value: length = 0: the ISAM index does not contain a value flag.

length 255 - KEYLEN - LOGLEN (cf. LOGLEN operand)

250

U3586-J-Z125-7-7600

VALPROP

=MIN

=MAX

VOLUME

FILE

Only for K-ISAM files; specifies how the value flag is to be included in the index entries (VALPROP = value propagation).

The VALPROP operand is ignored for NK-ISAM file.

VALPROP can also be specified as a NULL operand, in which case the VALPROP information from the catalog entry of the file will be transferred when the file is opened.

The lowest value of the value flag within each data or index block is included in the index entry at the next higher level; default value.

The highest value of the value flag within a data or index block is included in the index entry at the next higher level.

Specifies which private volumes are required for file processing. If a new file is to be created and neither DEVICE nor VOLUME is specified, the file will be processed on public volumes.

The VOLUME operand may be omitted if STATE=FOREIGN is specified and the system parameter VSEQPRI is set.

If private volumes are requested for processing of file generations whose group entry contains DISP=REUSE, the VOLUME specification will only be accepted until the maximum number of simultaneously existing generations is reached.

For disk files, only the first volume specified is used. In the case of tape files, the volumes specified in the VOLUME operand are added to the volume list in the catalog entry for the "oldest" generation.

Disk files

If the first private disk has at least the amount of space available as is requested by the SPACE operand or if SPACE is not specified, only the first private disk specified is requested. If SPACE requests more space than is available on the first private disk, a number of private disks are requested simultaneously. If further VSNs are specified, these are added to the volume list of the catalog entry for later extensions.

If a file is being extended, the SPACE operand must be specified at the same time with a primary allocation > 0; otherwise, the specified

VSNs will be ignored.

U3586-J-Z125-7-7600

251

FILE

252

Tape files

If "pathname" is not yet cataloged, the volume list in the VOLUME operand is added to the catalog entry. A connection to a TST can be established by specifying the TSET operand at the same time. In this case, the volume list is added to the TST entry and appended to any existing list. After the file has been opened, the catalog entry is updated using the volume list in the TST entry.

If "pathname" is already cataloged, the volume list in the catalog entry is extended by adding to it the volume list in the VOLUME operand. Consequently, VSNs that already exist in the catalog entry must not be specified with VOLUME.

The first volume from the volume list is requested by default

(exception: MOUNT=0). If more than one volume is to be mounted, the MOUNT operand must be used to specify how many volumes are to be mounted concurrently.

=PRIVATE Requests a private volume at the console.

=(PRIVATE,n) 1 n 9; requests "n" private volumes at the console.

=vsn

=(vsn,...)

The volume serial number (VSN) of the requested volume.

A list of up to 255 different VSNs of requested volumes.

VSEQ Only for cataloged tape files with standard labels; the VSEQ operand permits files to be processed in sections. A file section is that part of a multivolume file which is stored on one tape. The VSNs of all volumes belonging to the file are contained in the volume list of the catalog entry. Access to a specific volume is attained via the position of the corresponding VSN in the volume list of the catalog entry.

Example

If the VSN of the volume to be processed is in the fifth position in the volume list, the value "5" must be specified.

The VSEQ operand affects the structure of the TFT volume list:

If VSEQ is not specified, the VSNs are arranged in the TFT in the order that is specified in the VOLUME or TVSN operand.

If only one file section number is specified for VSEQ, all volumes as of the one identified are transferred to the TFT volume list.

If a list of file section numbers is specified for VSEQ, only the entries in the VSEQ list are transferred to the TFT volume list.

U3586-J-Z125-7-7600

FILE

=number 1 number 255; specifies the file section at which processing is to start.

If "pathname" is an output file (OPEN=OUTPUT/OUTIN), VSEQ=1 must be specified.

If "pathname" is opened or extended with OPEN EXTEND, VSEQ specifies the file section at which extension is to begin.

For files opened with OPEN REVERSE, only one file section number may be specified; automatic tape swapping is not supported with

OPEN REVERSE.

=(L(number,...))

WRCHK

=NO

=YES

WROUT

=NO

Specifies the order in which the file sections are to be processed.

This may be used only for input files, not for output files. For files opened with OPEN REVERSE, only one file section number may be specified and automatic tape swapping is not supported.

Write check; only for processing of disk files; specifies whether a read-after-write check is to be executed. "WRCHK" is not recorded in the catalog entry and must therefore be repeated each time before the file is opened or processed.

A "read-after-write" check implies a check for write errors. If an unrecoverable error is detected, control is passed to the EXLST exit

ERRADR. Owing to the additional disk accesses involved, this function has a markedly adverse effect on system performance.

No read-after-write check is executed; default value.

A read-after-write check is executed.

For ISAM processing; WROUT controls the reloading of updated blocks to disk.

Default value:

WROUT=NO for file processing with SHARUPD=NO

WROUT=YES for file processing with SHARUPD=YES

An updated block is not reloaded to disk until the contents of the buffer area in question must be replaced, or at the latest when the file is closed; default value.

This entry has no effect on K-ISAM files because updated blocks from these files are always reloaded to disk.

WROUT=NO only works for NK-ISAM files if WRITE-

IMMEDIATE=NO was specified when the ISAM pool being used was created.

U3586-J-Z125-7-7600

253

FILE

=YES Each updated block is reloaded to disk immediately, thus always ensuring the consistency of the data on disk and in virtual memory.

Note, however, that this also increases the I/O rate

Examples

Example 1a:

File link name and file attributes

In program X, assume that the following specifications have been made in the file control block (FCB) for an output file:

FILE=X.OUTPUT

LINK=OUTP

FCBTYPE=SAM

BLKSIZE=STD

Nothing is specified for DEVICE, which means that the system uses a public disk as the volume for this file.

Program X is called:

254

Fig. FILE-3 Matching the FCB to the TFT entry when a file is opened

The file is opened with the current FCB and the file is written to tape without anything in program X having to be changed.

U3586-J-Z125-7-7600

Example 1b

: Creating a TFT entry (with NULL operands)

(IN)

FILE MAX.FILE,LINK=LINKIN,FCBTYPE=,RECSIZE=,RECFORM=

RDTFT LINK=LINKIN,ALL

(OUT) % LINK=LINKIN

FILE=:W:$US123456.MAX.FILE

STATUS = INACTIVE

COMMAND = FILE

RETENT. PERIOD =NONE

OVWRITE PROTECT=NO

SECLEV

BYPASS

HIGH

NONE

DESTOC = NONE

FCBTYPE = NULL

RECFORM = NULL

BLKSIZE = NONE

KEYPOS = NONE

BLKCTRL = NONE

LOGLEN = NONE

OPEN = NONE

RECSIZE = NULL

BUFOFF = NONE

KEYLEN = NONE

POOLLNK = NONE

VALLEN = NONE

VALPROP = NONE

PAD = NONE

SHARUPD = NONE

LABEL = NONE

CODE

BLIM

= NONE

FSEQ = NONE

TAPEWR = NONE

DEVICE = NONE

VSN/DEV = PUBW02/D3480

DUPEKY = NONE

OVERLAP = NONE

WROUT = NONE

TPMARK = NO

TRANS = NONE

CHKPT = (NO,ACTIVE)

WRCHK = NONE

CLOSMSG = NONE

TSET NAME = NONE

FILE

U3586-J-Z125-7-7600

255

FILE

Example 2

: Creating a TFT entry (file attributes defined in the FILE command)

(IN)

FILE MAX.FILE.4,LINK=LINKIN,RECSIZE=100,RECFORM=F,RETPD=20,

BLKCTRL=DATA,POOLLNK=ISAMPOOL

RDTFT LINK=LINKIN,ALL

% LINK=LINKIN

FILE=:W:$US123456.MAX.FILE.4

STATUS = INACTIVE

COMMAND = FILE

RETENT. PERIOD =00020

OVWRITE PROTECT=NO

DESTOC = NONE

SECLEV = HIGH

BYPASS = NONE

FCBTYPE = NONE

RECFORM = FIXED LENGTH

BLKSIZE = NONE

KEYPOS = NONE

BLKCTRL = DATA

OPEN = NONE

RECSIZE = 00100

BUFOFF = NONE

KEYLEN = NONE

POOLLNK = ISAMPOOL

LOGLEN = NONE

VALPROP = NONE

PAD = NONE

SHARUPD = NONE

LABEL

CODE

BLIM

FSEQ

NONE

TAPEWR = NONE

DEVICE = NONE

VSN/DEV = PUBW11/D3480

VALLEN = NONE

DUPEKY = NONE

OVERLAP = NONE

WROUT = NONE

TPMARK = NO

TRANS = NONE

CHKPT = (NO,ACTIVE)

WRCHK = NONE

CLOSMSG = NONE

TSET NAME = NONE

256

U3586-J-Z125-7-7600

Example 3

: Allocating storage space on public volumes

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

FSTAT MAX.SPACE

% DMS0533 REQUESTED FILE NOT CATALOGED IN PUBSET ’W’. COMMAND TERMINATED

FILE MAX.SPACE

FSTAT MAX.SPACE,ALL

0000003 :W:$US123456.MAX.SPACE

FCBTYPE = NONE

LASTPG = 00000000

SHARE = NO

ACL = NO

CRDATE = NONE

VSNTYPE = PUB

2ND ALLO= 00003

ACCESS = WRITE

AUDIT

EXDATE

= NONE

DESTROY = NO

LADATE = NONE

EXPASS = NONE RDPASS = NONE

ACCESS# = 000

LARGE = NO

BLKTYPE = NONE

RECFORM = NONE

WRPASS = NONE

VERSION = 000

BACKUP = A

BLKSIZE = 000000

RECSIZE = 000000

PUBW24 / D3480 / 001

MIGRATE = ALLOWED

BLKCTRL = NONE

VSN/DEV/EXT =

EXTCNT =

:W: PUBLIC:

1 FILE RES= 3 FREE= 3 REL= 3 PAGES

COPY MAX.FILE,MAX.SPACE

FSTAT MAX.SPACE,ALL

0000003 :W:$US123456.MAX.SPACE

FCBTYPE = SAM VSNTYPE = PUB

LASTPG = 00000001

SHARE = NO

ACL = NO

CRDATE = 1990-12-18

RDPASS = NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

VSN/DEV/EXT =

EXTCNT =

:W: PUBLIC:

BLKSIZE = 002048

RECSIZE = 000000

PUBW24 / D3480 / 001

FILE

2ND ALLO= 00003

ACCESS

AUDIT

EXDATE = 1990-12-18

WRPASS = NONE

VERSION = 001

BACKUP

RES=

= WRITE

= NONE

= A

3 FREE=

DESTROY = NO

LADATE = 1990-12-18

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = PAMKEY

2 REL= 0 PAGES

FILE MAX.SPACE,SPACE=(100,20)

COPY MAX.FILE,MAX.SPACE

FSTAT MAX.SPACE,ALL

0000105 :W:$US123456.MAX.SPACE

FCBTYPE = SAM

LASTPG = 00000001

SHARE = NO

ACL = NO

CRDATE = 1990-12-18

VSNTYPE = PUB

2ND ALLO= 00020

ACCESS = WRITE

AUDIT = NONE

EXDATE = 1990-12-18

RDPASS = NONE

ACCESS# = 002

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

VSN/DEV/EXT =

EXTCNT =

:W: PUBLIC:

WRPASS = NONE

VERSION = 001

BACKUP = A

BLKSIZE = 002048

RECSIZE = 000000

PUBW24 / D3480 / 002

FILE RES= 105 FREE=

DESTROY = NO

LADATE

EXPASS

= 1990-12-18

= NONE

MIGRATE = ALLOWED

BLKCTRL = PAMKEY

104 REL= 102 PAGES

FILE

U3586-J-Z125-7-7600

257

FILE

(IN)

(OUT)

FILE MAX.SPACE,SPACE=-150

FSTAT MAX.SPACE,STANDARD

0000003 :W:$US123456.MAX.SPACE

FCBTYPE = SAM

LASTPG = 00000001

:W: PUBLIC: 1 FILE.

RES=

VSNTYPE = PUB

2ND ALLO= 00020

3, FREE= 2, REL=

(IN)

(OUT)

FILE MAX.PRIV.6,DEVICE=D3480,VOLUME=WORK02,SPACE=(100,20)

FSTAT MAX.PRIV.6,STANDARD

0000102*:W:$US123456.MAX.PRIV.6

FCBTYPE = SAM VSNTYPE = PUB

LASTPG = 00000000

:W: PRIVATE: 1 FILE.

RES=

2ND ALLO= 00020

102, FREE= 102, REL=

0 PAGES

99 PAGES

(IN)

(OUT)

FILE MAX.PRIV.6,SPACE=-150

FSTAT MAX.PRIV.6

0000003*:W:$US123456.MAX.PRIV.6

:W: PRIVATE: 1 FILE.

RES= 3, FREE=

(IN)

(OUT)

FILE MAX.FILE.6,SPACE=(100,20)

FSTAT MAX.FILE.6

0000102 :W:$US123456.MAX.FILE.6

:W: PUBLIC: 1 FILE.

RES= 102, FREE=

3, REL=

102, REL=

0 PAGES

102PAGES

(IN)

(OUT)

FILE MAX.FILE.6,SPACE=-150

FSTAT MAX.FILE.6

0000000 :W:$US123456.MAX.FILE.6

:W: PUBLIC: 1 FILE.

RES= 0, FREE= 0, REL= 0PAGES

258

U3586-J-Z125-7-7600

FILE

Example 4

: VSEQ operand=

/FILE A,VSEQ=2,VOLUME=V3,LINK=linkname

Volume list in the catalog before execution of the FILE command: (V1,V2)

Volume list in the catalog after execution of the FILE command: (V1,V2,V3)

TFT volume list: (V2,V3)

/FILE A,VSEQ=(L=(1,2)),LINK=linkname

Volume list in the catalog: (V1,V2,V3,V4)

TFT volume list: (V1,V2)

Example 5a

: TSET operand

/FILE A,VOLUME=V1,TSET=X,FSEQ=NEW,DEVICE=T1600,LINK=linkname1

/FILE B,VOLUME=V2,TSET=X,FSEQ=NEW,DEVICE=T1600,LINK=linkname2

The VSNs V1 and V2 are entered in the TST entry in accordance with the specifications in the TSET operand. The part of the catalog entry containing the list of volume serial numbers is structured as specified in the TST entry. If, in this example, the TST entry is created when the first FILE command is executed, the VSN list for file A contains the value (V1) and the list for file B contains (V1,V2), rather than only (V2), which would have been the case if the TSET operand had not been specified.

U3586-J-Z125-7-7600

259

FILE

Example 5b

: TSET operand

/FILE A,LINK=A,VOLUME=V1,TSET=X,FSEQ=NEW,DEVICE=T1600

After execution of this FILE command, the VSN V1 is inserted in the device table of the

TST entry "X" and cataloged for file A.

/FILE B,LINK=B,TSET=X,FSEQ=NEW,DEVICE=T1600

After execution of this FILE command, the VSN V1 is also cataloged for file B.

OPEN A

FEOV

CLOSE A,LEAVE

File A is created on the tape with VSN V1 and, due to the FEOV macro, extended on the next tape with the VSN V2, for example. V2 is then inserted in the device table for the TST entry "X" and added to the catalog entry for file A (see also EOV processing).

The tape sequence for file A thus contains the VSNs (V1,V2) and the pointer to the current tape in the TST entry "X" points to V2.

OPEN B

CLOSE B

Since the volume/tape pointer of TST entry "X" points to the tape with VSN V2, file B is written to this tape and the tape sequence for file B is thus (V2) instead of (V1).

260

U3586-J-Z125-7-7600

FILE

Example 6:

Tape dump with the PERCON utility routine

The pubset file MAX.TAPE.FILE is to be copied to tape. For this, the "copy"

MAX.TAPE.FILE.1 is first cataloged with a FILE command and the file MAX.TAPE.FILE is then copied.

The PERCON utility routine shows, in the SYSOUT log, the contents of the new tape file both in plain text and in hexadecimal notation. The SYSLST log (file

MAX.PERCON.2) shows only the printable text.

With the aid of the tables in the appendix, it is easy to see the structure of the labels.

The tape marks cannot be represented in printable form in the SYSLST log, nor can the block size and record length fields.

(*) in the log identifies PERCON statements

(IN)

(OUT)

(IN)

FILE MAX.TAPE.FILE.1,DEVICE=TAPE,VOLUME=D5260A

COPY MAX.TAPE.FILE,CMH.TAPE.FILE.1

% DMS0DE3 VOL D5260A FOR FILE :W:$US123456.MAX.TAPE.FILE.1 IS

MOUNTED ON DEVICE T0

EXEC $PERCON

% BLS0500 PROGRAM ’PERCON’, VERSION ’V2.2AB4’ OF ’87-06-11’ LOADED.

(IN)

(OUT)

% PER0000 PERCON BS2000 VERSION 2.2A00

volin volume=d5260a (*)

% DMS0DF6 INPUT TAPE WITH VSN D5260A HAS STD LABELS, BUT SHOULD BE

TREATED AS NSTD OR NO REPLY (0=EXIT; C=CONTINUE)?

(IN)

(OUT)

(IN)

% DMS0DE3 VOL D5260A FOR FILE :W:$US123456.PERCON.TPWORK.D.3686.VS0001

IS MOUNTED ON DEVICE T0 volout device=display edit (*)

(OUT) TMCNT: 000 BLOCK: 00000001

V O L 1 D 5 2 6 0 A

(00000) E5D6D3F1C4F5F2F6 F0C1404040404040 4040404040404040 4040404040404040

(00032) 4040404040404040 4040404040404040 4040404040404040 4040404040404040

(00064) 4040404040404040 40404040404040F1

TMCNT: 000

H D R 1 C M H .

BLOCK: 00000002

B A N D . D A T E I . 1 D 5 2 6 0 A 0 0 0 1 0

(00000) C8C4D9F1C3D4C84B C2C1D5C44BC4C1E3 C5C94BF140C4F5F2 F6F0C1F0F0F0F1F0

0 0 1 0 0 0 1 0 0 8 7 3 2 4 8 7 3 2 4 0 0 0 0 0 0 B S 2 0

(00032) F0F0F1F0F0F0F1F0 F040F8F7F3F2F440 F8F7F3F2F440F0F0 F0F0F0F0C2E2F2F0

0 0

(00064) F0F0404040404040 4040404040404040

TMCNT: 000

H D R 2 V 8 0 0

BLOCK: 00000003

0 1 0 2 0 4 8 0 /

00000) C8C4D9F2E5F8F0F0 F0F1F0F2F0F4F840 F061404040404040 4040404040404040

0 4

(00032) 4040404040404040 4040404040403180 0A33F0F440404040 4040404040404040

(00064) 4040404040404040 4040404040404040

TMCNT: 000 BLOCK: 00000004

H D R 3 Q M 2 8 6 0 1 8 C M H .

B A N D . D A T E I . 1

(00000) C8C4D9F3D8D4F2F8 F6F0F1F8C3D4C84B C2C1D5C44BC4C1E3 C5C94BF140404040

(00032) 4040404040404040 4040404040404040 4040404040404040 0000000000000000

0 0

(00064) 00000000F0F04040 4040404040404040

*** TAPE MARK ***

U3586-J-Z125-7-7600

261

FILE

TMCNT: 001 BLOCK: 00000001

D i e s i s t

(00000) 31800A3301000001 00000100002D0000 002D404000114040 C48985A24089A2A4 e i n e k l e i n e T e s t d a t e i .

(00032) 4085899585000A50 4092938589958500 0E4040E385A3A484 81A385894B000000

(00064) 0000000000000000 0000000000000000 0000000000000000 0000000000000000

*** *** 00061 IDENTICAL LINES SUPPRESSED

(02048) 0000000000000000 0000000000000000

*** TAPE MARK ***

TMCNT: 002 BLOCK: 00000001

E O F 1 C M H .

B A N D . D A T E I . 1 D 5 2 6 0 A 0 0 0 1 0

(00000) C5D6C6F1C3D4C84B C2C1D5C44BC4C1E3 C5C94BF140C4F5F2 F6F0C1F0F0F0F1F0

0 0 1 0 0 0 1 0 0 8 7 3 2 4 8 7 3 2 4 0 0 0 0 0 1 B S 2 0

(00032) F0F0F1F0F0F0F1F0 F040F8F7F3F2F440 F8F7F3F2F440F0F0 F0F0F0F1C2E2F2F0

0 0

(00064) F0F0404040404040 4040404040404040

TMCNT: 002

E O F 2 V 8 0 0

BLOCK: 00000002

0 1 0 2 0 4 8 0 /

(00000) C5D6C6F2E5F8F0F0 F0F1F0F2F0F4F840 F061404040404040 4040404040404040

0 4

(00032) 4040404040404040 4040404040403180 0A33F0F440404040 4040404040404040

(00064) 4040404040404040 4040404040404040

TMCNT: 002 BLOCK: 00000003

E O F 3 Q M 2 8 6 0 1 8 C M H .

B A N D . D A T E I . 1

(00000) C5D6C6F3D8D4F2F8 F6F0F1F8C3D4C84B C2C1D5C44BC4C1E3 C5C94BF140404040

(00032) 4040404040404040 4040404040404040 4040404040404040 0000000000000000

0 0

(00064) 00000000F0F04040 4040404040404040

*** TAPE MARK ***

(IN)

(OUT)

(IN)

(OUT) filout filnam=cmh.percon.2

(*)

% PER0033 LINK NAME ’PCOUT’ MULTIPLE USED. LAST STATEMENT IS VALID edit end

% PER0029 NUMBER OF HANDLED BLOCKS FOR LINK=PCIN: 16

(*)

% PER0030 NUMBER OF HANDLED RECORDS FOR LINK=PCOUT (FILE=MAX.PERCON.2): 8

% PER0031 PERCON NORMAL END

PERCON log: fileout

VOL1D5260A

HDR1MAX.TAPE.FILE.1 D5260A00010001000100 87324 87324 000000BS2000

HDR2V8000102048 0/

HDR3US123456MAX.TAPE.FILE.1

This is a small test file.

EOF1MAX.TAPE.FILE.1 D5260A00010001000100 87324 87324 000001BS2000

EOF2V8000102048 0/

EOF3US123456MAX.TAPE.FILE.1

262

U3586-J-Z125-7-7600

FILE

Example 7:

Creating a file set

The first file of the file set is created as a copy of a disk file (with no FSEQ specification).

(IN)

FILE MAX.TAPE.FILE.1,DEVICE=TAPE,VOLUME=D5260A

COPY MAX.TAPE.FILE,CMH.TAPE.FILE.1

The second file is created with the EDT file editor (LINK=EDTSAM). When EDT is terminated, the DMS issues the messages DMS0DE3 and DMSODE7:

(IN) FILE MAX.BAND.MF.DAT1,DEVICE=TAPE,VOLUME=D5260A,FSEQ=NEW,LINK=EDTSAM,BLKSIZE=30

(OUT)

%DMS0DE3 TAPE D5260A FOR FILE MAX.TAPE.MF.DAT1 ASSIGNED TO DEVICE A0

%DMS0DE7 TAPE-FILE MAX.TAPE.MF.DAT1 WITH LINK-NAME EDTSAM CLOSED,

BLOCK COUNT = 001

The third file MAX.BAND.MF.DAT2 is also created with the EDT:

(IN) FILE MAX.TAPE.MF.DAT2,DEVICE=TAPE,VOLUME=D5260A,FSEQ=NEW,LINK=EDTSAM,BLKSIZE=30

(OUT)

%DMS0DE3 TAPE D5260A FOR FILE MAX.TAPE.MF.DAT2 ASSIGNED TO DEVICE A0

%DMS0DE7 TAPE-FILE MAX.TAPE.MF.DAT2 WITH LINK-NAME EDTSAM CLOSED,

BLOCK COUNT = 001

The last file in the set is also created with the EDT:

(IN)

(OUT)

FILE MAX.TAPE.MF.DAT3,LINK=EDTSAM,DEVICE=TAPE,VOLUME=D5260A,FSEQ=NEW,BLKSIZE=20,-

RECFORM=F,RECSIZE=10,RETPD=2

%DMS0DE3 BAND D5260A FOR FILE MAX.TAPE.MF.DAT3 ASSIGNED TO DEVICE A0

%DMS0DE7 TAPE-FILE MAX.TAPE.MF.DAT3 WITH LINK-NAME EDTSAM CLOSED,

BLOCK COUNT = 002

U3586-J-Z125-7-7600

263

FILE

7a) PERCON tape dump

A tape dump of tape D5260A is written to a file using the PERCON utility routine. The log looks like this: The non-printable characters (e.g. in the block size and record length fields) are replaced in the log by "*".

VOL1D5260A

HDR1MAX.TAPE.FILE.1 D5260A00010001000100 87324 87324 000000BS2000

HDR2V8000102048 0/

HDR3US123456MAX.TAPE.FILE.1

****04

*** * * * * * This is a * small * test file.

EOF1MAX.TAPE.FILE.1 D5260A00010001000100 87324 87324 000001BS2000

EOF2V8000102048 0/

EOF3US123456MAX.TAPE.FILE.1

****04

HDR1MAX.BAND.MF.DAT1 D5260A00010002000100 87324 87324 000000BS2000

HDR2V000300003040/ 04

HDR3US123456MAX.TAPE.MF.DAT1

* * A * SHORT TEST:

* * FILE FSEQ1

EOF1MAX.BAND.MF.DAT1 D5260A00010002000100 87324 87324 000002BS2000

EOF2V000300003040/ 04

EOF3US123456MAX.TAPE.MF.DAT1

HDR1MAX.BAND.MF.DAT2 D5260A00010003000100 87324 87324 000000BS2000

HDR2V000300003040/

HDR3US123456MAX.TAPE.MF.DAT2

* * A * SHORT TEST:

* * FILE FSEQ1

EOF1MAX.TAPE.MF.DAT2 D5260A00010003000100 87324 87324 000002BS2000

EOF2V000300003040/ 04

EOF3US123456MAX.TAPE.MF.DAT2

HDR1MAX.BAND.MF.DAT3 D5260A00010004000100 87324 87326 000000BS2000

HDR2F000200001040/

HDR3US123456MAX.TAPE.MF.DAT3

ANOTHER SHORT TEST

OF FSEQ

EOF1MAX.TAPE.MF.DAT3 D5260A00010004000100 87324 87326 000002BS2000

EOF2F000200001040/ 00

EOF3US123456MAX.TAPE.MF.DAT3

264

U3586-J-Z125-7-7600

FSTATUS

FSTATUS Request catalog information

Application groups:

File processing (page 26 ff.)

Device and volume reservation (page 29)

Command description

The FSTATUS command serves to output information relating to catalog entries for files, file generations and file generation groups. This may consist simply of a list of names of files, etc. matching the criteria specified in the FSTATUS command, or of detailed information from the catalog entry. The user can obtain information about all files under his/her own user ID and about all shareable files owned by other users. Temporary files can only be addressed by their special prefix.

If the FSTATUS command is entered without operands, the reserved space and the path names of all files under the user’s ID are listed in alphabetical order. FSTATUS

HELP causes the syntax of the FSTATUS command to be output to SYSOUT (only effective in interactive mode). The FSTATUS output can be interrupted by means of the

BREAK function (K2 key).

Date entry format for the operands CRDATE, EXDATE and LADATE:

The date can be entered as an absolute or a relative value.

• Absolute date entry:

The date must be entered in the form YYYY-MM-DD, where YYYY is the year, MM the month and DD the day. The century may be omitted when entering the year, as can the leading zeros when entering the month or day.

The entry YYMMDD is also permitted.

• Relative date entry:

The date can also be entered in days, measured from the current day. It then has the form "-n" for the past and "+n" for the future, where "n" is the number of days.

Leading zeros may be omitted; the signs, however, are mandatory.

The following predefined concepts may be used for referring to short time spans:

Y[ESTERDAY] (where n = -1), T[ODAY] (n = +0/-0) and TOM[ORROW] (n = +1).

U3586-J-Z125-7-7600

265

FSTATUS

Format and operand description

Operation

FSTATUS

FSTAT

Operands pathname1

[ prefix

]

[,STANDARD][,CATALOG][,TRAITS][,PASSWORD]

[ [,ALL] ]

,RESERVED

READ

[,ACCESS]=

WRITE

]

[,ACL=

YES

]

[,BACKUP=

( C ,...)

]

NONE

OWNER=access-rights

[,BASIC-ACL=

( GROUP=access-rights [, ... ])

]

OTHERS=access-rights

266

U3586-J-Z125-7-7600

FSTATUS

Operation

FSTATUS

FSTAT

(cont.)

Operands

[,BLKCTRL=

NONE

PAMKEY

DATA

NONE

( PAMKEY ,...)

DATA

]

[,CRDATE= date

(date[,])

(,date)

(date1,date2)

]

[,EXDATE= date

(date[,])

(,date)

(date1,date2)

]

[,EXTENTS= number

(number[,])

(,number)

(number1,number2)

]

ISAM

BTAM

PAM

SAM

NONE

[,FCBTYPE=

ISAM

BTAM

( PAM ,...)

SAM

NONE

]

U3586-J-Z125-7-7600

267

FSTATUS

Operation

FSTATUS

FSTAT

(cont.)

Operands

SIZE number

[,FREESIZE= (number[,])

(,number)

(number1,number2)

]

CATALOG

[,FROM= LOCAL-PVS ]

(vsn,device)}

[,GEN=

YES

]

[,LADATE= date

(date[,])

(,date)

(date1,date2)

] value

(value[,])

(SYSOUT)

(SO)

(SYSLST)

(SL)

(PRINT)

(PR)

[,LIST= pathname2

(

(SYSOUT)

(SYSLST)

(PRINT) pathname2

STANDARD

FILENAM

)

ALLOWED

INHIBIT

[,MIGRATE =

(

ALLOWED

INHIBIT

,...)

]

268

U3586-J-Z125-7-7600

FSTATUS

Operation

FSTATUS

FSTAT

(cont.)

Operands

RDPASS

WRPASS

EXPASS

NONE

[,PASS=

RDPASS

( WRPASS ,...)

EXPASS

NONE

]

[,SHARE= SPECIAL ]

YES

FREESIZE number

[,SIZE= (number[,])

(,number)

(number1,number2)

]

[,SORT=

FILENAM

]

[,STATE=

NOCLOS

PCLOSE

]

[,STORAGE-LEVEL =

( S1 ,...)

]

[,SUPPORT=

PUBLIC

PRDISC

TAPE

PUBLIC

( PRDISC ,...)

TAPE

]

[,TYPE=FGG]

[,VOLUME=vsn]

[,VTOC=

YES

]

U3586-J-Z125-7-7600

269

FSTATUS

Positional operands

pathname1 catid stands for [:catid:][$userid.][filename]

File selection operand;"pathname" determines from which files information is to be requested. Temporary files are not included. You

can use wildcards in "catid" and "filename" (see page 46).

"pathname" must not be longer than 80 characters.

Catalog ID of the pubset containing the file. Default value: the catalog ID assigned to the user ID (JOIN entry).

userid User ID assigned to the file. Default value: the user ID from the

LOGON command.

Multiprocessor systems (see also "MSCF" manual)

Any "catid" or "userid" may be specified. Three different cases must be distinguished:

Neither "catid" nor "userid" is specified:

All file entries relating to the job-specific user ID which are contained in the catalog whose ID is assigned to that user ID are displayed.

"catid" is specified, "userid" is not specified:

All file entries relating to the job-specific user ID which are contained in the catalog with the specified "catid" are displayed. In this case, the command has the format: FSTAT :catid:

Only "userid" is specified:

The file entries relating to the specified "userid" and having the default catalog ID for that "userid" are displayed.

270

U3586-J-Z125-7-7600

filename prefix

FSTATUS

Fully or partially qualified name of a permanent or temporary file, of a file generation, or file generation group. The list below shows the possible specifications and their meanings: pathname1 Meaning

:catid: Information about all of the user’s files cataloged under "catid".

:catid:

$userid.

filename

Own user ID: information about all files cataloged with "catid" under the user’s ID.

Foreign user ID: information on all files which are on the specified pubset ("catid") and for which the user has access rights.

Temporary files are not included.

"filename" fully or partially qualified; own user ID: information about all files on the default pubset that are addressed by

"filename"; temporary files are not included.

Foreign user ID: information about the files addressed by "filename" if the user has access rights for those files.

:catid:

$userid.

filename

"filename" fully or partially qualified; own user ID: information about all files on the specified pubset that are addressed by

"filename"; temporary files are not included.

Foreign user ID: information about the files addressed by "filename" on the specified pubset if the user has access rights for those files.

File selection operand; information about all temporary files for the current job can be requested by specifying the special prefix character for temporary files only (# or @, defined at system generation time). However, in the SYSOUT or SYSLST log, the file name plus prefix specified by the user is replaced by the file name used internally by the system, whereby the prefix is replaced by the character string "S.nnn.tsn".

U3586-J-Z125-7-7600

271

FSTATUS

BACKUP

Keyword operands (in alphabetical order)

ACCESS

=READ

=WRITE

File selection operand; supplies information about the files/file generations for which read-only or read/write access is permitted.

Supplies information about files for which only read access is permitted.

Supplies information about files for which both read and write access are permitted.

ACL

=N[O]

=Y[ES]

ALL

File selection operand; the file is selected on the basis of the ACL entry.

Files that have no ACL entry are to be selected.

Files that have an ACL entry are to be selected.

Information selection operand; the information from STANDARD,

CATALOG and TRAITS is combined. The table "Meaning of output

fields", which starts on page 284 lists the output fields alphabetically,

and gives details on their possible values.

BASIC-ACL

=NONE

File selection operand; selects files on the basis of the ARCHIVE or

HSMS save level specified. A number of save levels may also be specified in list form, in which case all files and FGGs which satisfy one of these conditions are included (logical OR operation).

Selects files/FGGs with the attribute BACKUP=A.

Selects files/FGGs with the attribute BACKUP=B.

Selects files/FGGs with the attribute BACKUP=C.

Selects files/FGGs with the attribute BACKUP=D.

Selects files/FGGs with the attribute BACKUP=E.

File selection operand; selects files in accordance with the BASIC-

ACL entry. Specifications within a user class are combined by means of a logical OR operation (see also the "DMS Introductory

Guide and Command Interface" [8]).

Files that have no BASIC-ACL entry are to be selected.

272

U3586-J-Z125-7-7600

FSTATUS

=YES

=(...)

Files that have a BASIC-ACL entry are to be selected.

Files are to be selected on the basis of individual specified access rights.

OWNER= Files for which the owner has at least one of the specified access rights are to be selected.

GROUP= Files for which members of the user’s group have have at least one of the specified access rights are to be selected.

OTHERS= Files files for which members of other groups have at least one of the specified access rights are to be selected.

access-rights mean:

NO-ACCESS

[NO]

([R[EAD]= ],[W[RITE]=

YES

NO-ACCESSNo access authorization;

[NO]

YES

],[[E]X[EC]=

[NO]

YES

])

READ

=NO

=YES

WRITE

=NO

=YES

EXEC

=NO

=YES read access;

Not allowed;

Allowed;

Write access

Not allowed;

Allowed;

Execute access

Not allowed;

Allowed;

BLKCTRL

=NONE

=PAMKEY

=DATA

File selection operand; selects on the basis of file type, depending on the block format with which the file was stored (defined via the

BLKCTRL operand of the FILE command).

The BLKCTRL type is not to be used as selection criterion.

Files created with BLKCTRL=PAMKEY - i.e. files which have a separate PAM key - are to be selected.

Files created with BLKCTRL=DATA - i.e. whose block control information is kept in a block control field at the start of each data block - are to be selected.

U3586-J-Z125-7-7600

273

FSTATUS

=NO

CATALOG

CRDATE

Files with no block control information are to be selected.

Information selection operand; outputs information about the currently occupied storage space and about the attributes of files, file generations and file generation groups defined using CATALOG commands (for more details, refer to table "Meaning of the output

fields, starting on page 284).

The following catalog entry fields are output for each selected file:

Output field

ACCESS

ACCESS#

ACL

AUDIT

BACKUP

CRDATE

DESTROY

EXDATE

EXPASS

GROUP

LADATE

LARGE

MIGRATE

OTHERS

OWNER

RDPASS

VERSION

WRPASS

Meaning

Permitted access (read/write)

Access counter

ACL entry exists: yes/no

Monitoring by system exit routines

Backup/save level for ARCHIVE

Date of last write access

Automatic data destruction: yes/no

Expiration date (date as of which write access is permitted)

Execute password exists: yes/no

Access rights for your user group

Last access date

Complete ARCHIVE backup: yes/no

Migration permitted (yes/no)

Access rights for other user groups

Access rights for your user group

Read password exists: yes/no

Shareability: yes/no

Internal ARCHIVE attribute

Write password exists: yes/no

This is followed by total lines indicating the storage space occupied by the listed files, divided into groups according to volume type

(public/private/tape). File generations are not included unless

GEN=YES is specified (see the description for "STANDARD").

File selection operand; selects files on the basis of their creation dates or the dates of their last write accesses. Area data includes the specified limit values in each case. The format of the date specification is described in the command description above.

Dates which lie in the future are meaningless for CRDATE.

274

U3586-J-Z125-7-7600

FSTATUS

=date

=(date[,])

=(,date)

=(date1,date2)

Selects files last accessed for writing on the specified date.

Selects files created or updated between the specified date and the current date.

Selects files last accessed for writing before the specified date.

Selects files last accessed for writing during the specified period

(date1 < date2).

EXDATE

=date

=(date[,])

=(,date)

File selection operand; selects files based on their expiration date, i.e. the date on which a defined retention period expires. Future dates indicate that the retention period for the respective file is still in effect. For the format of the date specification, see the command description above.

Selects files which contain precisely the date specified in the

EXDATE field.

Selects files whose retention period expires on or after the date specified in the EXDATE field.

Selects files whose retention period expires on or before the specified date.

=(date1,date2)

Selects files whose expiration date lies within the specified period

(date1 < date2).

EXTENTS

=number

File selection operand; selects files on the basis of the number of extents they occupy. These are counted in the EXTCNT field of the catalog entry.

0 number 65535; selects files with precisely the specified number of extents.

=(number[,])

=(,number)

Selects files with at least the specified number of extents.

Selects files with no more than the specified number of extents.

=(number1,number2)

Selects files with a number of extents within the specified range

(number1 < number2).

U3586-J-Z125-7-7600

275

FSTATUS

FCBTYPE

=NONE

=ISAM

=BTAM

=SAM

=PAM

File selection operand; selects files on the basis of the access method with which they were created. If a list of access methods is specified, the system links them by means of a logical OR operation and provides information about all files which satisfy one of the specified conditions.

Selects files which are cataloged but contain no data, i.e. files which have not yet been opened or files which have been erased by means of /ERASE...,SPACE.

Returns information about ISAM files.

Returns information about BTAM files.

Returns information about SAM files.

Returns information about PAM files.

FREESIZE

=SIZE

Selects files and file generation groups on the basis of the size of their free (= reserved but unused) space.

Selects files for which the number of free PAM pages is equal to the number of reserved pages.

=number 0 number 16777215; selects files with precisely the specified number of free PAM pages.

Selects files with at least the specified number of free PAM pages.

=(number[,])

=(,number) Selects files with no more than the specified number of free PAM pages.

=(number1,number2)

Returns information about files whose number of free PAM pages lies within the specified range (number1 < number2).

FROM

=CATALOG

Defines the source for the information that is to be output.

The output information is to be derived from the catalog of the default pubset for the user ID, i.e. the catalog with the default catalog ID (JOIN entry).

=LOCAL-PVS The output information is to be derived from the system catalogs of all selected local pubsets.

276

U3586-J-Z125-7-7600

FSTATUS

=(vsn,device) The output information is to be derived from the directory of the private disk designated by "vsn". The device type ("device") of this private disk must be specified. Permissible values for "device" can be found in the device table in the appendix. The operands VOLUME,

SUPPORT and VTOC must not be specified.

GEN Specifies whether or not information about file generations is to be returned.

Default value: GEN=NO

=NO

=YES

The following table shows the interaction of the GEN operand with the operand TYPE=FGG.

LADATE

=date

Operand combinations in the current FSTATUS command

TYPE=FGG GEN=YES GEN=NO x x x x x x

Information about

FGGs file generafiles tions

* x Specification in the FSTATUS command

* Included in the command output

Not included in the command output

The specification GEN=YES is effective only if no "filename" is included in "pathname1".

Selects files, file generations and FGGs on the basis of the date of the last access to the file. If the fields CRDATE and LADATE contain the same date, the last access was a write access; if CRDATE <

LADATE the last access was only a read access. For the format of date specification see the command description above. Future dates such as TOMORROW are meaningless in this case.

Selects files whose field LADATE contains precisely the specified date.

U3586-J-Z125-7-7600

277

FSTATUS

=(date[,])

=(,date)

=(date1,date2)

Selects files which have been accessed since the specified date.

Selects files which have not been accessed since the specified date.

Selects files last accessed during the specified period (date1 < date2).

L[AST]P[AGE]

=value

=(value,)

=(,value)

Selects files on the basis of the number of written PAM blocks (tape files: number of blocks according to the block counter BLKCNT); 0

value 16777215.

Selects files with precisely the specified number of written PAM blocks.

Selects files with at least the specified number of written PAM blocks.

Selects files with no more than the specified number of written PAM blocks.

=(value, value)

Selects files whose number of written PAM blocks lies within the specified range.

LIST Specifies the output medium for current FSTATUS processing. The requested information is output in the form of a table.

The operands STANDARD, CATALOG, TRAITS, PASSWORD, ALL and RESERVED may not be specified together unless the FSTATUS output is sent to SYSOUT.

(SYSOUT)

(SO)

In interactive mode, the FSTATUS output is sent to the user’s terminal and is determined by the operands STANDARD, CATALOG,

TRAITS, ALL, RESERVED and PASSWORD; default value.

(SYSLST)

(SL)

The FSTATUS output is sent to the system file SYSLST; the type of output is determined by the additional specification STANDARD or

FILENAM (see below). SYSLST can be assigned (beforehand) to a temporary or permanent file by means of a SYSFILE command.

278

U3586-J-Z125-7-7600

FSTATUS

(PRINT)

(PR)

=pathname2

The FSTATUS output is sent directly to a printer. The type of output is determined by the additional specification STANDARD or FILENAM

(see below).

The FSTATUS output is written to the file specified here by

"pathname2". The type of output is determined by the additional specification STANDARD or FILENAM (see below). "pathname2" must not be identical to "pathname1".

pathname2 stands for :catid:$userid.filename

:catid: userid filename

Catalog ID

User ID

Fully-qualified name of a file or file generation

=(,STANDARD)

The FSTATUS command generates an edited list with the following information:

Output field

FILENAME

PAM PAGES

FREE PAGES

SECOND ALLOC.

FCBTYPE

ACCESS

PASSWORDS

BKL

#EXT

VOLUME

Meaning

File/path name

Reserved storage space

Reserved but unused storage space

Secondary allocation

Access method at file creation time

Shareable: yes/no

Permissible access type: read/write

Passwords exist: yes/no

Backup/save level

Total number of extents for the file

Volume serial number of the volume

=(,FILENAM) Generates an unedited list with the names of the files, file generations and file generation groups in question (the first byte of each output record is X’40’).

MIGRATE

=ALLOWED

=INHIBIT

Only for files and FGGs on disk; files are selected on the basis of the migration option.

Selects files and file generation groups for which migration is permitted.

Selects files and file generation groups for which migration is not permitted.

U3586-J-Z125-7-7600

279

FSTATUS

PASS

=NONE

=RDPASS

=WRPASS

=EXPASS

PASSWORD

RESERVED

=YES

=NO

=SPECIAL

Selects files and file generation groups depending on the password defined in the CATALOG command. If more than one password type is specified in the form of a list, the system logically ORs them and provides information on all files which satisfy one of the specified conditions.

Selects files for which there is no password protection.

Returns information on which files are protected by read passwords.

The actual passwords are not shown.

Returns information about files which are protected by write passwords. The actual passwords are not shown.

Returns information about files which are protected by execute passwords. The actual passwords are not shown.

Returns information about the type of password protecting a file or file generation group. The actual passwords are not shown. If you have forgotten your password, you must ask the system administrator for assistance.

The total lines for the amount of storage space occupied are also output (see the description of "STANDARD" and also "Meaning of output fields").

Returns information about the storage space occupied by the files

(and file generations, since GEN=YES is implied) selected by the current FSTATUS command. Simultaneous specification of

STANDARD, CATALOG, PASSWORD or ALL is ignored.

Selects files and file generation groups on the basis of their shareability. If "$userid." is a foreign user ID, SHARE=YES is automatically implied.

Returns information about files which are shareable.

Selects files which may be accessed only by their owners.

Selects files which the maintenance user ID $SERVICE may access.

280

U3586-J-Z125-7-7600

FSTATUS

SIZE

=FREESIZE

=number

=(number[,])

Requests information about files and file generations on the basis of the size of the reserved storage space.

Selects files for which the number of reserved PAM pages is equal to the number of free pages.

Selects files with precisely the specified number of reserved PAM pages.

Selects files with at least the specified number of reserved PAM pages.

=(,number) Selects files with not more than the specified number of reserved

PAM pages.

=(number1,number2)

Selects files whose number of reserved PAM pages lies within the specified range (number1 < number2).

SORT

=FILENAM

=NO

STANDARD

Specifies how the catalog entries and/or path names are to be sorted for output.

The catalog entries and/or path names are sorted alphabetically for output; default value.

The catalog entries and/or path names are output in the order in which they are kept in the catalog.

Returns information primarily about current storage space occupancy

(see "Meaning of output fields", page 284).

The following catalog field entries are output for each selected file:

Output field

FCBTYPE

VSNTYPE

LASTPG

2ND ALLO

Meaning

Access method at file creation time

Volume type (public/private)

Number of occupied PAM pages

Secondary allocation

U3586-J-Z125-7-7600

281

FSTATUS

282

This is followed by total lines indicating the storage space occupied by the listed files, classified by volume types (public/private/tape).

File generations are included only if GEN=YES is specified.

Output field Meaning

:catid:

FILES

RES

FREE

REL

Catalog ID

Number of files per volume type

Total number of reserved PAM pages

Total number of unused PAM pages

Total number of PAM pages which can be released

STATE

=NOCLOS

=PCLOSE

Selects files and file generations on the basis of whether they are open or whether a pseudo-close has been issued for them.

Returns information about output files which have been opened via an OPEN macro (OPEN OUTIN, INOUT or OUTPUT) and files which were not closed in a previous system run or because of job abortion. GEN=YES is implied.

Selects files for which a pseudo-close has been issued (only for spoolout files).

STORAGE LEVEL

Selects files depending on which storage level they are on (for more information see the "HSMS" manual).

If more than one operand value is specified, they are logically ORed.

=S0

=S1

=S2

Selects files on storage level S0.

Selects files migrated to storage level S1.

Selects files migrated to storage level S2.

SUPPORT

=PUBLIC

=PRDISC

=TAPE

TYPE=FGG

Selects files, file generations and file generation groups on the basis of the type of volume on which they are stored. If a list of volume types is specified, these are logically ORed by the system.

Returns information about files, etc. stored on public volumes.

Returns information about files, etc. stored on private disks.

Returns information about files/FGs/FGGs stored on tape.

Suppresses information about files and returns only information about file generation groups and file generations (see GEN=YES).

U3586-J-Z125-7-7600

TRAITS

FSTATUS

Returns information primarily about the file and file generation attributes defined via the FILE command or FCB macro and about the specific attributes of file generation groups (see "Meaning of

output fields", page 284).

The following catalog entry fields are output for each selected file:

Output field

BASE

BLKCTRL

BLKTYPE

BLKSIZE

BUFOFF

CODE

DISP

EXTCNT

FIRSTGN

FSEQ

GEN

KEYLEN

KEYPOS

LABEL

LASTGN

LOGLEN

RECFORM

RECSIZE

STORAGE-LEVEL

VALLEN

VALPROP

VSN/

DEV/

EXT

Meaning

Appears for FGGs only: base value for relative generation numbers

Block control information

Block type (standard/non-standard block)

Block size (= buffer length)

Buffer offset (tape files)

Code used (tape files)

Appears for FGGs only: action when the maximum number of simultaneous generations is reached

Appears for disk files only: total number of extents for the file

Appears for FGGs only: oldest cataloged generation

Appears for tape files only: file sequence number

Appears for FGGs only: maximum number of concurrently cataloged generations

ISAM key length

ISAM index position

Appears for tape files only: standard version of the labels

Appears for FGGs only: youngest/latest cataloged generation

Length of the ISAM logical flag

Record format

Record length

Storage hierarchy level

Length of the ISAM value flag

Propagation of the ISAM value flag

Volume serial number of the volume

Device type for the volume

Number of extents on the volume

This is followed by total lines indicating the storage space occupied by the listed files, classified by volume types (public/private/tape).

File generations are included only if GEN=YES is specified. (see the description of "STANDARD").

U3586-J-Z125-7-7600

283

FSTATUS

VOLUME=vsn

VTOC

=NO

=YES

Returns information on all files and file generation groups which have the specified volume serial number ("vsn") in their volume list.

Specifies whether the requested information is to be taken from the

VTOC (= Volume Table Of Contents) of a private disk or from the system file catalog $TSOSCAT.

The VTOC operand is ignored for files that are not on a private volume, for partially qualified file names, or if it is specified in conjunction with GEN=YES.

Returns the current entry from the system catalog TSOSCAT; default value.

Returns the VTOC catalog entries (from the F1 label of a private disk) in accordance with the last current status in the entire computer network. The related volume must be assigned.

The VTOC entry from the private volume replaces the corresponding

TSOSCAT entry. This makes it possible to re-establish consistency between the VTOC and TSOSCAT entries if, for example, files of a shared private disk have been modified by a job running on another computer. If the specified file no longer exists on the private volume shown in the $TSOSCAT entry, the catalog entry is deleted.

All other keyword operands are ignored when VTOC=YES.

Meaning of output fields

Header line n a numeric character alphanumeric character

Output field

File size

Structure

nnnnnnn

:catid:

$userid.

filename

Meaning

7-digit number; specifies the number of PAM pages reserved for the file

Catalog ID of the pubset on which the file is cataloged

User ID (max. 8 characters) of the file

Name of the permanent or temporary file, file generation or file generation group for which information is output

284

U3586-J-Z125-7-7600

FSTATUS

File attributes

Output field

ACCESS

Values

WRITE

READ

ACCESS# nnn

ACL

AUDIT

BACKUP

BASE

E nnnnn

YES/NO

NONE

ALL

SUCC

FAIL

Description

Write access to the file is permitted.

Only read access to the file is permitted, not write access.

3-digit number indicating the number of accesses to the file. This is set to 0 when the file is created and incremented by

1 each time the file is opened. The maximum value is 255 and is not changed once this value has been reached.

Specifies whether or not the file is protected by an ACL entry.

No monitoring by system exit routines is defined for the file.

All DMS actions for the files are monitored.

All successful DMS actions are monitored.

All unsuccessful DMS actions are monitored.

The file is saved in each backup run.

The file is saved in backup runs for files with the attribute BACKUP=B/C/D.

The file is saved in backup runs for files with the attribute BACKUP=C/D.

The file is saved in backup runs for files with the attribute BACKUP=D.

This file is not automatically saved by

ARCHIVE.

Only for file generation groups:

5-digit number indicating the absolute generation number currently used as the base for relative generation numbers.

U3586-J-Z125-7-7600

285

FSTATUS

Output field

BLKCNT

BLKCTRL

BLKSIZE

BLKTYPE

BUFOFF

CODE

CRDATE

DESTROY

DEV

Values

nnnnnnn

DATA

NONE

PAMKEY

UNKNOWN nnnnnn

Description

For tape files: 7-digit number indicating the number of data blocks in the file.

The block control information is in the data block.

No block control information available.

The file has not yet been opened.

Block control information is in the PAM key.

The file has an undefined BLKCTRL value.

6-digit number indicating the buffer size in bytes.

STD

(STD,n) nn For tape files: buffer offset.

EBCDIC/ISO7/ For tape files: code table with which

OWN the file was created.

yy-mm-dd yy = year; mm = month; dd = day; creation date of the file, i.e. the date of the last write (update) access.

00-00-00

Standard blocks: buffer size = 1 PAM page

The blocking factor (n the file.

16) defined for

The file has never been opened or has been erased with /ERASE file; DATA.

No data destruction.

YES aaaaa

Data destruction for disk files; for tape files: residual data is overwritten when tapes are swapped and tape files are closed.

The device type specification for the volume

(cf. the device type list in the appendix).

286

U3586-J-Z125-7-7600

FSTATUS

Output field

DISP

Values

CYCLE

REUSE

EXDATE

EXPASS

EXT

EXTCNT

DELETE

KEEP nnn

* nnn yy-mm-dd

NONE

YES

Description

Only for file generation groups: when the GEN limit is reached, the oldest file and its catalog entry are erased.

Only for file generation groups: when the GEN limit is reached, the oldest file and its catalog entry are erased; for files on private volumes, the new generation is stored on the volume which becomes free.

Only for file generation groups: when the GEN limit is reached, all existing generations are erased.

Only for file generation groups: when the GEN limit is reached, no file generations are automatically erased; this is not done until a CATALOG command with the operand STATE=U is entered for the FGG.

yy = year; mm = month; dd = day;

The date until which the file is locked against write access, i.e. the file cannot be updated or erased.

No execute password is defined for the file.

The file is protected by an execute password, i.e. the file cannot be executed

(/EXEC, /DO, /CALL, /ENTER) unless this password is specified.

The number of extents for the file on the volume designated by "VSN".

The file has no extents on the volume designated by "VSN".

Total number of extents for the file

U3586-J-Z125-7-7600

287

FSTATUS

Output field

FCBTYPE

FIRSTGN

FSEQ

GEN

GROUP

KEYLEN

KEYPOS

LABEL

LADATE

Values

NONE

ISAM/BTAM/

SAM/PAM/

PAM(PLAM) nnnnn nnnnn nnnnn r-w-x nnn nnnnn

(STD,n)

NSTD

NO yy-mm-dd

Description

There is only a catalog entry for the file; the file has never been opened; storage space may have been allocated (see CRDATE).

The access method with which the file was created.

Only for file generation groups:

5-digit absolute generation number of the oldest generation cataloged for this file generation group.

For tape files:

5-digit number indicating the position of the file in an MF set.

Only for file generation groups:

5-digit number indicating the maximum number of generations which may be cataloged simultaneously for this file generation group.

Group members’ access rights

Only for ISAM files:

3-digit number indicating the length of the

ISAM key in the ISAM index (in bytes).

Only for ISAM files:

5-digit number indicating the position of the ISAM key in the record.

For tape files with standard labels: the interchange level for DIN 66029, and thus the labels with which the file was created.

Identifies tape files with non-standard labels.

Identifies tape files without labels.

yy = year; mm = month; dd = day; the date of the last access to the file.

288

U3586-J-Z125-7-7600

FSTATUS

Output field

LARGE

Values

YES

LASTGN nnnnn

LASTPG

LOGLEN

MIGRATE

RDPASS

RECFORM nnnnnnn nnn

(V,)

(F,)

(U,)

(,A)

(,M)

(,N)

ALLOWED

INHIBIT

NONE

YES

Description

Save runs with ARCHIVE always save the entire file.

Save runs with ARCHIVE save only the PAM pages of the file which have been updated since the last save run.

Only for file generation groups:

5-digit absolute generation number of the youngest generation cataloged for the file generation group.

7-digit number indicating the number of PAM pages occupied by the file (only for files with standard blocks).

Only for ISAM files which have a logical flag in the ISAM index:

3-digit number indicating the length of the logical flag in the ISAM index (in bytes).

HSMS is allowed to migrate the file to background storage.

The file must not be migrated.

No read password exists for the file.

A read password has been defined for the file, i.e. read access is possible only after specifying this password.

Specifies: a) the record type defined for the file, b) valid printer control characters

- the file contains variable-length records;

- the file contains fixed-length records;

- the file contains records with undefined length.

- ASA control characters are valid for the file;

- EBCDIC control characters are valid for the file;

- the file contains no printer control characters.

U3586-J-Z125-7-7600

289

FSTATUS

Output field

RECSIZE

Values

nnnnn

00000

SHARE NO

YES

SPECIAL

STORAGE-LEVEL S1 / S2

OTHERS

OWNER

VALLEN r-w-x r-w-x nnn

VALPROP

VERSION

MIN

MAX nnn

Description

5-digit number indicating the length in bytes defined for the records of the file

(for RECFORM=F) or the maximum permissible record length (for RECFORM=V).

For files with FCBTYPE NONE and CRDATE

NONE: together with RECFORM=V/U: maximum record length = BLKSIZE

The file is not shareable.

The file is shareable.

The file may be accessed under the user ID for maintenance personnel ($SERVICE).

For migrated files only (HSMS): the file has been migrated to the specified storage level.

Access rights for others

Owner’s access rights

Only for ISAM files which have a value flag in the ISAM index:

3-digit number indicating the length of the value flag in the ISAM index (in bytes).

Only for ISAM files which have a value flag in the ISAM index: the lowest value flag in each data or index block is placed in the related index entry in the next higher level.

Only for ISAM files which have a value flag in the ISAM index: the highest value flag in each data or index block is placed in the related index entry in the next higher level.

3-digit version number of the file.

290

U3586-J-Z125-7-7600

FSTATUS

Output field

VSN

Values

PUBxaa xx.aaa

xxx.aa

xxxx.a

aaaaaa

VSNTYPE

WRPASS

2ND ALLO

PUB

PVT

NONE

YES nnnnn

Description

Catalog ID (x) and VSN (aa) or the public volume on which space is reserved for the file. Format for one-character catalog ID.

Catalog ID (x..) and VSN (a..) of the public volume on which space is reserved for the file. Format for a multi-character catalog

6-character alphanumeric volume serial number of the private volume on which the file occupies space.

The file is stored on public volumes

(tape or disk).

The file is stored on private volumes

(tape or disk).

There is no write password for the file.

A write password is defined for the file, i.e. write access is possible only if this password is specified.

5-digit number indicating the value defined for secondary allocation.

U3586-J-Z125-7-7600

291

FSTATUS

Total lines

Output field

:catid:

Values

catid

FREE

PRIVATE n n FILES

PUBLIC

REL

RES

SUM

TAPE n FILES n n n-FILES

Description

Catalog ID of the pubset on which the files are cataloged.

Number of reserved but unused PAM pages on the volume.

Number of files cataloged in the specified pubset which are stored on private volumes.

Number of files cataloged in this pubset.

Number of PAM pages on the volume that could be released.

Number of PAM blocks reserved on the volume.

Separate total lines for PUBLIC and

PRIVATE; see above for a description of the output fields.

Number of cataloged files stored on tape.

292

U3586-J-Z125-7-7600

FSTATUS

Examples

Example 1:

Standard function of the FSTATUS command

(IN)

(OUT)

FSTAT

0000030 :W:$US123456.EXAMP.FS.1

0000000 :W:$US123456.EXAMPLES

0000030 :W:$US123456.EXAMPLES.COPY

0000003 :W:$US123456.MAX.DO.ASS.MAC

0000003 :W:$US123456.MAX.DO.ASS.MAL

0000030 :W:$US123456.MAX.PROTO.FSTAT.ALL.FGG

0000030 :W:$US123456.MAX.PROTO.SEC.WAIT

0000000 :W:$US123456.GROUP.LISTS (FGG)

0000000 :W:$US123456.GROUP.PROTO (FGG)

0000000 :W:$US123456.TEST

0000000 :W:$US123456.TEXST

0000000 :W:$US123456.TEXT

0000030 :W:$US123456.ZE.EXAMP.FSTAT.10

0000030 :W:$US123456.ZE.EXAMP.FSTAT.11

0000030 :W:$US123456.ZE.EXAMP.FSTAT.7

0000030 :W:$US123456.ZE.EXAMP.FSTAT.8

0000030 :W:$US123456.ZE.EXAMP.FSTAT.9

:W: PUBLIC: 17 FILES. RES= 256, FREE= 215, REL=

(01)

201 PAGES

(01) The FSTAT command without operands outputs an alphabetical list of all files cataloged for the user ID of the current job. The first column (e.g. 0000030) shows the number of PAM pages reserved for each file. This is followed by the path name: :catid:$userid.filename.

The last line shows the number of file names listed (FILES), the number of PAM pages reserved for these files (RES), how many of these pages are free (FREE), and how many could be released (REL). "PUBLIC" or "PRIVATE" indicates the volume type and :catid: shows the catalog ID under which the files are cataloged.

U3586-J-Z125-7-7600

293

FSTATUS

Example 2:

SORT=NO operand

(IN)

(OUT)

FSTAT ,SORT=NO

0000000 :W:$US123456.GROUP.LISTS (FGG)

0000030 :W:$US123456.MAX.PROTO.FSTAT.ALL.FGG

0000000 :W:$US123456.GROUP.PROTO (FGG)

0000030 :W:$US123456.MAX.PROTO.SEC.WAIT

0000000 :W:$US123456.EXAMPLES

0000030 :W:$US123456.EXAMP.FS.1

0000030 :W:$US123456.EXAMPLES.COPY

0000030 :W:$US123456.ZE.EXAMP.FSTAT.7

0000030 :W:$US123456.ZE.EXAMP.FSTAT.8

0000000 :W:$US123456.TEXT

0000030 :W:$US123456.ZE.EXAMP.FSTAT.9

0000000 :W:$US123456.TEST

0000000 :W:$US123456.TEXST

0000030 :W:$US123456.ZE.EXAMP.FSTAT.10

0000030 :W:$US123456.ZE.EXAMP.FSTAT.11

:W: PUBLIC: 17 FILES. RES= 256, FREE= 214, REL=

(01)

201 PAGES

(01) All files cataloged under this user ID are listed in the order in which they appear in the catalog.

294

U3586-J-Z125-7-7600

FSTATUS

Example 3:

Wildcards in the file name (cf. example 6c)

(IN)

(OUT)

FSTAT *BEISP*

0000030 :W:$US123456.EXAMP.FS.1

0000000 :W:$US123456.EXAMPLES

0000030 :W:$US123456.EXAMPLES.COPY

0000003 :W:$US123456.MAX.FSTAT.EXAMP.2

0000030 :W:$US123456.ZE.EXAMP.FSTAT.2

0000030 :W:$US123456.ZE.EXAMP.FSTAT.3

:W: PUBLIC: 6 FILES. RES= 123, FREE= 115, REL=

(01)

111 PAGES

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

FSTAT BEISP*

0000030 :W:$US123456.EXAMP.FS.1

0000000 :W:$US123456.EXAMPLES

0000030 :W:$US123456.EXAMPLES.COPY

:W: PUBLIC:

FSTAT EXAMP.

3 FILES. RES= 60, FREE=

0000030 :W:$US123456.EXAMP.FS.1

:W: PUBLIC: 1 FILE.

RES=

FSTAT EXAMPLES.

0000030 :W:$US123456.EXAMPLES.COPY

:W: PUBLIC:

FSTAT EXAMPLES

1 FILE.

RES=

30, FREE=

0000000 :W:$US123456.EXAMPLES

:W: PUBLIC: 1 FILE.

RES=

FSTAT TE*T

0000000 :W:$US123456.TEST

0000000 :W:$US123456.TEXST

0000000 :W:$US123456.TEXT

:W: PUBLIC:

FSTAT TE/T

3 FILES. RES=

0000000 :W:$US123456.TEST

0000000 :W:$US123456.TEXT

:W: PUBLIC: 2 FILES. RES=

0, FREE=

56, REL=

28, REL=

0, REL=

(02)

54 PAGES

(03)

27 PAGES

(04)

27 PAGES

(05)

0 PAGES

(06)

0 PAGES

(07)

0 PAGES

(01) The character ’*’ replaces any character string - in this case before and after the string "EXAMP"; i.e. all files which contain the string "EXAMP" anywhere in their names will be listed.

(02) The character ’*’ replaces any character string - in this case after the string

"EXAMP": all files whose names begin with "EXAMP" will be listed.

(03) The partial qualification "EXAMP." selects all files where the first partial name in the file name is "EXAMP.".

(04) This selects all files whose first partial name is "EXAMPLES.".

(05) "EXAMPLES" selects one, and only one file: the file with the fully qualified file name "EXAMPLES".

(06) "*" replaces any character string between the strings "TE" and "T".

(07) The character "/" replaces just one character between the strings "TE" and "T".

U3586-J-Z125-7-7600

295

FSTATUS

Example 4:

Partial qualification

(IN)

(OUT)

FS MAX.

0000003 :W:$US123456.MAX.DO.ASS.MAC

0000003 :W:$US123456.MAX.DO.ASS.MAL

0000150 :W:$US123456.MAX.L.ANHANG

0000030 :W:$US123456.MAX.L.EX1-57.MAC

0000060 :W:$US123456.MAX.L.EX1-57.NEW

0000030 :W:$US123456.MAX.L.EX60-92

0000030 :W:$US123456.MAX.PROTO.FSTAT.FGG

0000003 :W:$US123456.MAX.S.APPENDIX

0000003 :W:$US123456.MAX.S.EX1-57

0000003 :W:$US123456.MAX.S.EX1-57.NEW

0000003 :W:$US123456.MAX.S.EX60-92

:W: PUBLIC: 13 FILES. RES= 573, FREE=

(01)

115, REL= 96 PAGES

(01) All files which are addressed by the partial qualification "MAX." are selected.

Example 5:

Catalog entry for a temporary file

(IN)

(OUT)

(IN)

(OUT)

FSTAT #

% DMS0533 SPECIFIED FILE IN PUBSET ’W’ NOT FOUND.

CMD TERMINATED

CAT #TEMP

COPY MAX.FILE,#TEMP

FSTAT #TEMP,ALL

0000003 :W:$US123456.S.nnn.tsn.TEMP

FCBTYPE = SAM

LASTPG = 00000001

SHARE = NO

ACL = NO

CRDATE = 1990-12-18

VSNTYPE = PUB

2ND ALLO= 00003

ACCESS = WRITE

AUDIT

EXDATE

= NONE

= 1990-12-18

RDPASS = NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

VSN/DEV/EXT =

EXTCNT =

:W: PUBLIC:

WRPASS = NONE

VERSION = 001

BACKUP = E

BLKSIZE = 002048

RECSIZE = 000000

PUBW06 / D3480 / 001

FILE RES= 3 FREE=

(02)

(03)

(04)

DESTROY = NO

LADATE = 1990-12-18

EXPASS = NONE

MIGRATE = INHIBIT

BLKCTRL = PAMKEY

2 REL=

(01)

0 PAGES

(01) The message shows that no temporary files exist for this job.

(02) The CATALOG command creates a temporary file.

(03) Temporary files can be processed just like permanent files: here, the file

MAX.FILE is copied into the file #TEMP.

(04) The catalog entry for a temporary file differs from that of a permanent file created with the default attributes in the field BACKUP=E. In addition, the internal path name of the file is shown: the prefix "#" is converted by the system into the character string S.nnn.tsn, where "nnn" is a unique number generated by the system and "tsn" is the TSN of the current job.

296

U3586-J-Z125-7-7600

FSTATUS

Example 6a:

CATALOG operand

(IN)

(OUT)

FSTAT MAX.FILE,CATALOG

0000003 :W:$US123456.MAX.FILE

ACL

= NO

ACCESS = WRITE

AUDIT = NONE

CRDATE = 1990-12-18

RDPASS = NONE

ACCESS# = 002

LARGE

:W:

= NO

PUBLIC:

EXDATE

WRPASS

= 1990-12-18

= NONE

VERSION = 001

BACKUP = A

1 FILE RES= 3 FREE=

(01)

DESTROY = NO

LADATE = 1990-12-18

EXPASS = NONE

MIGRATE = ALLOWED

2 REL= 0 PAGES

(01) An extract from the catalog entry for MAX.FILE is returned. This contains the file attributes to be defined with the CATALOG command.

Example 6b

: RESERVED operand

(IN)

(OUT)

FSTAT ,R

:W: PUBLIC:

:W: PRIVATE:

64 FILES. RES=

3 FILES. RES=

780, FREE=

48, FREE=

503, REL=

46, REL=

(01)

441 PAGES

42 PAGES

(01) Only the total lines for all files cataloged under the user ID of the current job in the default catalog (:W:) are shown.

Example 6c

: PASSWORD operand

(IN)

(OUT)

FSTAT TE*T*,PASSWORD

0000000 :W:$US123456.TEST

RDPASS = YES WRPASS = NONE

0000000 :W:$US123456.TEST.FILE

EXPASS = NONE

RDPASS = NONE WRPASS = YES

0000003 :W:$US123456.TEXST

RDPASS = NONE WRPASS = NONE

0000003 :W:$US123456.TEXT

RDPASS = NONE WRPASS = NONE

0000003 :W:$US123456.TEXT.1

RDPASS = NONE WRPASS = NONE

EXPASS

= NONE

EXPASS = NONE

0000003 :W:$US123456.TEXT.2

RDPASS = NONE

:W: PUBLIC:

WRPASS = NONE

6 FILES. RES=

EXPASS

12, FREE=

= NONE

8, REL=

(01)

0 PAGES

(01) The output shows for which files passwords have been defined.

U3586-J-Z125-7-7600

297

FSTATUS

Example 7

: Selection of files with specific attributes

(IN)

(OUT)

FSTAT ,PASS=NONE

0000024 :W:$US123456.MAX.PROTO.COPY.2

0000024*:W:$US123456.FILE.NEW

0000000 :W:$US123456.GROUP.DATA (FGG)

0000024*:W:$US123456.PRIV.DAT.1

0000024*:W:$US123456.PRIV.DAT.2

0000024*:W:$US123456.PRIV.DAT.3

0000024*:W:$US123456.PRIV.DAT.4

0000000 :W:$US123456.TEST

0000024*:W:$US123456.TEST.PRIV

0000000 :W:$US123456.TEST.PUB

0000024*:W:$US123456.TEST.2.PRIV

0000000 :W:$US123456.TEXST

:W: PUBLIC: 5 FILES. RES=

:W: PRIVATE: 7 FILES. RES=

24, FREE=

168, FREE=

(01) All files which are not protected by passwords are listed.

6, REL=

156, REL=

(01)

51 PAGES

144 PAGES

(IN)

(OUT)

FS ,STATE=NOCLOS

0000030 :W:$US123456.MAX.PROTO.FSTAT.ALL.FGG

:W: PUBLIC: 1 FILE.

RES= 30, FREE= 30, REL=

(01) All files open when the FSTATUS command is entered are listed.

(IN)

(OUT)

FSTAT ,SUPPORT=PRDISC

0000024*:W:$US123456.FILE.NEW

0000024*:W:$US123456.PRIV.DAT.1

0000024*:W:$US123456.PRIV.DAT.2

0000024*:W:$US123456.PRIV.DAT.3

0000024*:W:$US123456.PRIV.DAT.4

0000024*:W:$US123456.TEST.PRIV

0000024*:W:$US123456.TEST.2.PRIV

:W: PRIVATE: 7 FILES. RES= 168, FREE=

(01) All files stored on private disks are listed.

156, REL=

(01)

30 PAGES

(01)

144 PAGES

(IN)

(OUT)

FSTAT ,SIZE=(2,8)

0000003 :W:$US123456.MAX.DO.ASS.MAC

0000003 :W:$US123456.MAX.DO.ASS.MAL

0000006 :W:$US123456.GS.D.B

0000003 :W:$US123456.GS.DO.ASS

0000003 :W:$US123456.GS.DO.EXAMP

0000003 :W:$US123456.TEXT.DAT1

0000003 :W:$US123456.TEXT.1

0000003 :W:$US123456.TEXT.2

:W: PUBLIC: 8 FILES. RES= 27, FREE= 10, REL=

(01)

0 PAGES

(01) All files are listed for which at least two and not more than eight PAM pages are reserved.

298

U3586-J-Z125-7-7600

FSTATUS

Example 8:

File generation groups and file generations

Example 8a:

List of cataloged FGGs with their generations

(IN)

(OUT)

FSTAT ,TYPE=FGG,GEN=YES

0000000 :W:$US123456.GROUP.LISTEN (FGG)

0000003 :W:$US123456.GROUP.LISTEN(*0010)

0000003 :W:$US123456.GROUP.LISTEN(*0011)

0000000 :W:$US123456.GROUP.LISTEN(*0012)

0000000 :W:$US123456.GROUP.PROTO (FGG)

0000003 :W:$US123456.GROUP.PROTO(*0001)

0000003 :W:$US123456.GROUP.PROTO(*0002)

0000003 :W:$US123456.GROUP.PROTO(*0003)

0000003 :W:$US123456.GROUP.PROTO(*0004)

:W: PUBLIC: 9 FILES. RES= 21, FREE= 7, REL=

(01)

0 PAGES

(01) The group entries of all cataloged file generation groups and the path names of all related and cataloged file generations are listed.

Example 8b: Complete catalog entries of an FGG on public volume

(IN)

(OUT)

FSTATUS MAX.GROUP.RES,GEN=YES,ALL

00000000 :N:$D89116.MAX.GROUP.RES (FGG)

ACL

= NO

ACCESS = WRITE

AUDIT = NONE

CRDATE = 1991-01-14

RDPASS = NONE

ACCESS# = 000

LARGE

GEN

= NO

= 00003

FIRSTGN = 00003

EXDATE

WRPASS

LASTGN

= 1991-01-14

= NONE

VERSION = 000

BACKUP = A

BASE = 00002

= 00005

00000003 :N:$D89116.MAX.GROUP.RES(*0003)

FCBTYPE = SAM

LASTPG = 00000001

VSNTYPE = PUB

2ND ALLO= 00003

ACL

= NO

ACCESS = WRITE

AUDIT = NONE

CRDATE = 1991-01-14

RDPASS = NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

VSN/DEV/EXT =

EXTCNT = 1

EXDATE = 1991-01-14

WRPASS = NONE

VERSION = 001

BACKUP = A

BLKSIZE = 002048

RECSIZE = 000000

PUBN01 / D3480 / 001

(01)

DESTROY = NO

LADATE = NONE

EXPASS = NONE

MIGRATE = ALLOWED

DISP = CYCLE

DESTROY = NO

LADATE = 1991-01-14

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = PAMKEY

U3586-J-Z125-7-7600

299

FSTATUS

(OUT)

00000003 :N:$D89116.MAX.GROUP.RES(*0004)

FCBTYPE = SAM

LASTPG = 00000001

VSNTYPE = PUB

2ND ALLO= 00003

ACL

= NO

ACCESS = WRITE

AUDIT = NONE

CRDATE = 1991-01-14

RDPASS = NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

VSN/DEV/EXT =

EXTCNT = 1

EXDATE = 1991-01-14

WRPASS = NONE

VERSION = 001

BACKUP = A

BLKSIZE = 002048

RECSIZE = 000000

PUBN02 / D3480 / 001

DESTROY = NO

LADATE = 1991-01-14

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = PAMKEY

00000003 :N:$D89116.MAX.GROUP.RES(*0005)

FCBTYPE = SAM VSNTYPE = PUB

LASTPG = 00000001

SHARE = NO

2ND ALLO= 00003

ACCESS = WRITE

ACL = NO

CRDATE = 1991-01-14

RDPASS = NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

RECFORM = (V,N)

AUDIT

EXDATE

WRPASS

= NONE

= 1991-01-14

= NONE

VERSION = 001

BACKUP = A

BLKSIZE = 002048

RECSIZE = 000000

PUBN03 / D3480 / 001 VSN/DEV/EXT =

EXTCNT =

:N: PUBLIC:

4 FILES RES= 9 FREE=

DESTROY = NO

LADATE = 1991-01-14

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = PAMKEY

6 REL= 0 PAGES

(01) The complete catalog entries of the file generation group, the group entry and the file generations are to be output.

300

U3586-J-Z125-7-7600

FSTATUS

Example 8c:

Complete catalog entries of an FGG on private disk

(IN)

(OUT)

FSTAT MAX.GROUP,GEN=Y,A,VOLUME=WORK01

0000000*:W:$US123456.MAX.GROUP (FGG)

SHARE = NO ACCESS = WRITE

ACL = NO

CRDATE = 1991-01-14

AUDIT = NONE

EXDATE = 1991-01-14

RDPASS = NONE

ACCESS# = 000

LARGE = NO

GEN = 00005

FIRSTGN = 00002

VSN/DEV =

WRPASS = NONE

VERSION = 000

BACKUP = A

BASE = 00000

LASTGN = 00006

WORK01 / D3480

0000003*:W:$US123456.MAX.GROUP(*0002)

FCBTYPE = NONE VSNTYPE = PVT

LASTPG = 00000000

SHARE = NO

ACL = NO

CRDATE = NONE

2ND ALLO= 00003

ACCESS

AUDIT

EXDATE

= WRITE

= NONE

RDPASS = NONE

ACCESS# = 000

LARGE = NO

BLKTYPE = STD

RECFORM = NONE

VSN/DEV/EXT =

EXTCNT = 1

WRPASS = NONE

VERSION = 000

BACKUP = A

BLKSIZE = 000000

RECSIZE = 000000

WORK01 / D3480 / 001

0000003*:W:$US123456.MAX.GROUP(*0003)

FCBTYPE = NONE VSNTYPE = PVT

LASTPG = 00000000

SHARE = NO

2ND ALLO= 00003

ACCESS = WRITE

ACL = NO

CRDATE = NONE

RDPASS = NONE

ACCESS# = 000

LARGE = NO

BLKTYPE = STD

RECFORM = NONE

VSN/DEV/EXT =

EXTCNT = 1

AUDIT = NONE

EXDATE = NONE

WRPASS = NONE

VERSION = 000

BACKUP = A

BLKSIZE = 000000

RECSIZE = 000000

WORK01 / D3480 / 001

(01)

DESTROY = NO

LADATE = NONE

EXPASS = NONE

MIGRATE = ALLOWED

DISP = CYCLE

DESTROY = NO

LADATE = NONE

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = NONE

DESTROY = NO

LADATE = NONE

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = NONE

U3586-J-Z125-7-7600

301

FSTATUS

0000003*:W:$US123456.MAX.GROUP(*0006)

FCBTYPE = NONE

LASTPG = 00000000

VSNTYPE = PVT

2ND ALLO= 00003

ACL

= NO

ACCESS = WRITE

AUDIT = NONE

CRDATE = NONE

RDPASS = NONE

ACCESS# = 000

LARGE = NO

BLKTYPE = STD

EXDATE = NONE

WRPASS = NONE

VERSION = 000

BACKUP = A

BLKSIZE = 000000

RECFORM = NONE

VSN/DEV/EXT =

EXTCNT = 1

:W: PRIVATE: 4 FILES. RES=

RECSIZE = 000000

WORK01 / D3480 / 001

9, FREE= 9, REL=

DESTROY = NO

LADATE = NONE

EXPASS = NONE

MIGRATE = ALLOWED

BLKCTRL = NONE

0 PAGES

(01) The complete catalog entries for the file generation group (group entry) and for the cataloged file generations are listed. Note that the group entry is on private disk WORK01, but other private disks also contain generations (*0004 and

*0005) belonging to this file generation group.

Example 9:

Catalog entry of a tape file

(IN)

(OUT)

FSTAT TAPEFILE,A

:W:$US123456.TAPEFILE

FCBTYPE = SAM

BLKCNT = 00000001

VSNTYPE = PVT

ACL

= YES

= NO

CRDATE = 91-02-02

RDPASS = NONE

ACCESS# = 001

LARGE = NO

BLKTYPE = STD

ACCESS

AUDIT

= WRITE

= NONE

EXDATE = 91-02-02

WRPASS = NONE

VERSION = 001

RECFORM = (V,N)

CODE = EBCDIC

BUFOFF = 04

VSN/DEV

:W: TAPE:

BACKUP = A

BLKSIZE = 002048

RECSIZE = 002048

LABEL

= ( D5193A / TAPE

1 FILE.

= (STD,1)

)

DESTROY = NO

LADATE = 91-02-02

EXPASS = NONE

BLKCTRL = PAMKEY

FSEQ = 00001

302

U3586-J-Z125-7-7600

GETJV

GETJV Output job variable value

Application group: Job variable functions (page 36)

The GETJV command is only available with the JV software product (see also "Job

Variables" manual [11]).

Command description

The GETJV command outputs the value of a user job variable or a special job variable to SYSOUT.

Format and operand description

Operation

GETJV

Operands jvid

(jvid[,start][,length])

CHAR

HEX

][,PASS=password] jvid start length

This entry may contain one of the following types of job variable names: jvname

*jvlink special-jvname

Denotes the fully-qualified name of a permanent or temporary job variable.

Specifies a job variable link name.

Denotes the name of a special job variable.

Specifies the start position within the job variable value. If "start" is omitted, "1" is used. The start position must be between 1 and 256.

Specifies the number of bytes to be output. 1 length 256. "start" plus "length" must not exceed 257.

Default value: length of the job variable value.

If the length of the job variable value, from the specified start position to the end of the JV value, differs from the number of bytes specified in "length", the smaller of these two values will be used. An attempt to read a non-existent (sub)string (e.g. a string whose start position lies outside the job variable value) will result in an error message.

U3586-J-Z125-7-7600

303

GETJV

CHAR

HEX

PASS=password

Specifies that the value is to be output as a character constant; default value.

Specifies that the value is to be output as a hexadecimal constant.

Specifies the password required for reading the job variable (see the

CATVJ command).

If the password is incorrect, the command is rejected, unless the correct password was previously entered in the password table by means of a PASSWORD command.

Examples: see the "Job Variables" manual [11].

304

U3586-J-Z125-7-7600

GETUS

GETUS Read user switches

Command description

The GETUS command enables users to obtain information about the setting of their own and any other user ID’s switches. The numbers of all switches set to ON are displayed.

32 user switches are provided for each user ID. They are numbered from 0 through 31 and stored in the JOIN file of the home pubset.

When a user ID is created, all of its 32 switches are set to OFF. Any switches that ARE subsequently set to ON will retain this setting even after LOGOFF.

The current job can be controlled by means of these user switches (SKIPUS or WHEN command).

Format and operand description

Operation

GETUS

Operands

[userid] userid User ID. Default value: user ID as specified with the LOGON command.

Example

(IN) LOGON XY,ABR00007,C’MAI’

......

(IN) GETUS

(OUT) % SWITCHES ON EQUAL-

(OUT) % 1, 2, 3, 10

(IN) GETUS BBMP

(OUT) % ALL SWITCHES SET OFF

(01)

(02)

(01) User switches 1, 2, 3 and 10 of user ID "XY" have already been set to on during previous jobs.

(02) All user switches for user ID "BBMP" are set to OFF.

For a further example, see the SKIPUS command.

U3586-J-Z125-7-7600

305

HELP

HELP Display message text

Application group: Device and volume reservation (page 29)

Command description

The HELP command displays the text of a system message on SYSOUT. You can also request descriptive text and specify the preferred language for the display of message text.

Format and operand description

Operation

HELP msgid

Operands msgid

[

LIST

]

[,INFORMATION=[

][

]]

[,LANGUAGE=language]

4- or 7-character message code. The corresponding message text is output to SYSOUT.

INFORMATION

LANGUAGE

=language

Displays the system message in normal form. F, together with D, is the default value. (F stands for "FULL MESSAGE").

Displays the system message together with an explanation of the message text. D, together with F, is the default value. (D stands for

"DESCRIPTION").

Displays the system message in coded abbreviated form (C stands for "CODE").

Displays only the message text. (M stands for "MINI").

Specifies the language for the output of system messages and descriptive text.

1 letter, e.g. "E" for English, "D" for German. The symbols for additional languages are given in the "System Messages" manual

[24] or may be obtained from the system administrator.

306

U3586-J-Z125-7-7600

HELP

LIST Repeats the system message which was last displayed for the task.

Messages requested using the HELP command are not included here.

Examples

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

FSTATUS XXXXX (01)

% DMS0533 REQUESTED FILE NOT CATALOGED ON PVS W. COMMAND TERMINATED

HELP LAN=D (02)

% DMS0533 SPECIFIED FILE IN PVS W NOT FOUND. CMD TERMINATED

% This message is issued by DMS commands. The requested file is not

% cataloged in the requested PVS.

% None.

HELP INF=C (03)

% DMS0533 W

% This message is issued by DMS commands. The requested file is not

% cataloged in the requested PVS.

% None.

HELP INF=M

% DMS0533 REQUESTED FILE NOT CATALOGED ON PVS W. CMD TERMINATED

(04)

HELP INF=M,LAN=D

% DMS0533 SPECIFIED FILE IN PVS W NOT FOUND. CMD TERMINATED

(05)

HELP BLS0500,INF=M,LAN=D

% BLS0500 PROGRAMM ’(&00)’, VERSION ’(&01)’ OF ’(&02)’ LOADED.

% COPYRIGHT (&04) (&05)

(06)

HELP INF=M,LAN=D

% DMS0533 SPECIFIED FILE IN PVS W NOT FOUND. CMD TERMINATED

(07)

(01) The file specified by /FSTATUS is not cataloged; message DMS0533 is displayed.

(02) The last message issued is to be repeated; the message text, together with descriptive text, is output in German (default).

(03) The last message issued is displayed in coded abbreviated form.

(04) The last message issued is displayed in "mini" format.

(05) The last message issued is displayed in German and in "mini" format.

(06) Message BLS0500 issued by the linking loader is requested by means of the

HELP command. It is displayed in German and in "mini" format.

(07) The text of the last message issued (DMS0533) is requested again. Message

BLS0500 is ignored since it was requested explicitly using the HELP command.

U3586-J-Z125-7-7600

307

HOLD

HOLD Place TFT entry in hold status

Command description

The HOLD command is used to place an entry in the task file table (TFT) in the hold status. This serves to defer the subsequent RELEASE command (or REL macro) for this

TFT entry until a DROP command with the relevant file link name is issued.

If the TFT entry is changed by means of the CHANGE command, it remains in hold status under its new name.

TFT entries in the hold status can be edited at any time by means of the FILE command.

Format and operand description

Operation

HOLD

Operands

[link] link Specifies the file link name of a TFT entry to be placed in the hold status. If no entry with this name existed previously, a new TFT entry is created for this link name. Further entries can then be made in this TFT entry by means of the FILE command.

If "link" is not specified, the first TFT entry with link name

C’ ’ is processed.

308

U3586-J-Z125-7-7600

HOLD

Examples:

Example 1:

/FILE LINK=X,...

/HOLD X

/RELEASE X

/DROP X

An entry with the name X is created in the task file table.

The hold status indicator is set for TFT entry X.

The entry X is not deleted, since it is subject to the

HOLD indicator. However, the command (or REL macro) sets the RELEASE indicator in TFT entry X.

Only now does the RELEASE command or REL macro take effect, the TFT entry X being deleted and any associated private devices released.

Example 2:

/HOLD Y An entry with the name Y is created in the TFT and its

HOLD status indicator is set.

/FILE LINK=Y,...

This command uses the existing TFT entry Y, and makes entries in it.

/DROP Y

The HOLD status for entry Y is cancelled. As no RELEASE has been issued, no operation is performed.

/RELEASE Y Entry Y is no longer subject to HOLD.

The RELEASE command thus has the immediate effect of deleting entry Y.

Example 3:

/FILE LINK=A

/HOLD A

/CHANGE A,B

/DROP A

/RELEASE B

/DROP B

The name of TFT entry A is changed to B, but everything else in the entry remains the same, e.g. the entry B is now subject to the HOLD status.

This command generates an error message as there is no longer an entry with this link name.

The RELEASE indicator is set in TFT entry B, but the command is deferred since HOLD is in force.

RELEASE takes effect, i.e. entry B (formerly entry Y) is deleted.

U3586-J-Z125-7-7600

309

IMPORT

IMPORT Create catalog entry for private files

Command description

The IMPORT command catalogs files stored on private disks if they were created under the user ID of the job issuing the command. DMS takes the file attributes from the F1 label of the private disk and places them in the catalog entry. The command can process partially qualified file names, which means that the user can import several files with a single command.

When importing file generation groups with generations stored on different disks, please note that generations are cataloged only if the group entry already exists in the system catalog or is kept on the first disk to be imported. Otherwise, the catalog entries for the generations imported before the group entry will be missing. These generations must then be cataloged afterwards using an IMPORT or FILE command (STATE=FOREIGN).

The functions of the commands IMPORT and ERASE (operands CATALOG/DELETE-

OR-EXPORT and VOLUME, respectively) are not exact opposites. When a volume is exported, DMS deletes the catalog entries for all files which occupy storage space on this volume. If the same volume is reimported, DMS creates catalog entries only for those files which begin on the volume (i.e. files which received space on the volume during their primary allocation).

Locked entries can be imported from the F1 label. If, however, entries in the user catalog have to be replaced (REPLACE=YES/ABS), the entries must not be locked and write access must be permitted.

310

U3586-J-Z125-7-7600

IMPORT

Format and operand description

Operation

IMPORT

Operands

[pathname,]VOLUME=vsn,DEVICE=device

YES

[,REPLACE= ABS ]

YES

ONLY

[,LIST=

YES

( NO

ONLY

SYSLST

, SYSOUT )

BOTH

]

[,GEN=

YES

][,PVSID=catid]

NO pathname userid filename stands for: [$userid.]filename

Designates the files, file generation groups or file generations to be cataloged. If "pathname" is not specified, DMS catalogs all files, etc.

which are stored under the user ID of the current job on the private disk specified in the VOLUME operand.

For file generations and file generation groups, create the group entry before cataloging the generations.

User ID; default value: the user ID specified in the LOGON command.

Fully or partially qualified name of a file, file generation group or file generation.

DEVICE=device

Device type for the volume; see the device table in appendix A.1 for possible entries for "device" (under the "Device type" column).

U3586-J-Z125-7-7600

311

IMPORT

312

GEN

=YES

=NO

For file generation groups: specifies whether only the group entry or also the file generations stored on the same private disk is/are to be cataloged.

If the group entry is on the private disk, DMS catalogs the FGG and all related generations which start on this disk. If there is no group entry on the disk or in the user catalog, no file generations are cataloged; GEN=YES is the default value.

DMS transfers only the group entry of the FGG to the catalog.

LIST

=YES

=NO

=ONLY

Specifies how command execution is to be logged (see the table

"Return codes/messages" below).

Command processing is logged; LIST=YES is the default value.

No information about command processing is returned.

Causes execution of the IMPORT command to be simulated, not actually carried out, i.e. the users receives a SYSOUT/SYSLST log which shows how the IMPORT command would have been executed. The log contains a list (depending on "pathname") of the files on the volume specified by VOLUME, together with the messages and information returned by the IMPORT command.

DMS does not check, at this time, whether file locks or protection attributes would prevent import of the files. For the actual import, you must ensure that the files are not locked and that write access is permitted.

=(...,SYSLST)

=(...,SYSOUT)

Command execution is logged on SYSOUT. Only the return code is shown (see below).

=(...,BOTH)

Command processing is logged to SYSLST. The log contains the return code and the message texts (see table "Return codes/ messages" below); LIST=(...,SYSLST) is the default value.

Command execution is logged on SYSLST and SYSOUT. The

SYSLST log contains the return code and the message texts, while the SYSOUT log contains only the return code.

PVSID=catid Specifies the pubset in which the files are to be cataloged. If this is omitted, the catalog entries are created under the default catalog ID of the user ID.

U3586-J-Z125-7-7600

IMPORT

REPLACE

=NO

=YES

=ABS

VOLUME=vsn

Specifies whether an existing "old" catalog entry is to be overwritten.

DMS does not overwrite the existing catalog entry; REPLACE = NO is the default value.

The old catalog entry is overwritten if it does not match the specifications in the IMPORT command.

The cataloged file is stored on a public disk: the catalog entry is overwritten, which means that the public file is erased (providing the protection attributes permit this and the file is not locked; otherwise, the old catalog entry is left unchanged).

The cataloged file is on private disk, but begins on a volume other than the one specified in the VOLUME operand: the catalog entry is overwritten (providing the protection attributes permit this and the file is not locked; otherwise, the old entry remains unchanged).

The old catalog entry is overwritten even if the catalog entry and the specifications in the IMPORT command match. The return code shows whether the entry was overwritten (return code 8) or whether a file lock prevented overwriting (return code 9).

Volume serial number ("vsn") of the private disk on which the files to be imported are stored.

U3586-J-Z125-7-7600

313

IMPORT

Return codes/messages

314

U3586-J-Z125-7-7600

IMPORT

Examples

(IN)

(OUT)

IMPORT ,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,SYSOUT)

0 :W:$US123456.FILE.NEW

0 :W:$US123456.TEST.PRIV

0 :W:$US123456.TEST.2.PRIV

All files stored for $US123456 (user ID of the current job) on private disk WORK02 are imported.

Return code on SYSOUT: 0 (a new catalog entry was created and the file imported).

(IN)

(OUT)

ERASE FILE.NEW

IMPORT FILE.NEW,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,BOTH)

% DMS05FE REQUESTED FILE(S) NOT FOUND

The "private" file FILE.NEW and its catalog entry were completely erased.

(IN)

(OUT)

ERASE TEST.PRIV,DEL-OR-EXP

IMPORT TEST.PRIV,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,BOTH)

0 :W:$US123456.TEST.PRIV

A * * * I M P O R T O U T P U T L I S T * * * 10:24:42 11/04/87

/IMPORT TEST.PRIV,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,BOTH)

OLD USER-ID CODE NEW USER-ID CODE

FILE DID NOT EXIST

FILE NAME

:W:$US123456.TEST.PRIV

Since only the catalog entry for TEST.PRIV was deleted, the file can be imported again with the IMPORT command.

Return code on SYSOUT: 0

Message on SYSLST:

FILE DID NOT EXIST

. (The IMPORT OUTPUT LIST is written to

SYSLST).

REPLACE operand

(IN)

(OUT)

ERASE TEST.PRIV,DEL-OR-EXP

COPY TEST.2.PRIV,TEST.PRIV

FSTAT TEST.PRIV

0000024 :W:$US123456.TEST.PRIV

:W: PUBLIC: 1 FILE.

RES= 24, FREE= 22, REL= 21 PAGES

The catalog entry for the "private" file TEST.PRIV is deleted and a new file TEST.PRIV is created on pubset W. 24 PAM pages are reserved for this file, but it actually occupies only 2 PAM pages (FREE = 22 PAGES).

U3586-J-Z125-7-7600

315

IMPORT

(IN)

(OUT)

IMPORT TEST.PRIV,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,BOTH)

2 :W:$US123456.TEST.PRIV

A * * * I M P O R T O U T P U T L I S T * * * 10:26:01 11/04/87

/IMPORT TEST.PRIV,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,BOTH)

OLD USER-ID CODE NEW USER-ID CODE

FILE EXISTS/REPLACE=NO

FILE NAME

:W:$US123456.TEST.PRIV

The IMPORT command is to catalog the "private" file TEST.PRIV again. Since the default value is REPLACE=NO, the pubset file TEST.PRIV is not erased.

Return code on SYSOUT: 2

Message on SYSLST:

FILE EXISTS/REPLACE=NO

. (The IMPORT OUTPUT LIST is written to SYSLST.)

(IN)

(OUT)

IMPORT TEST.PRIV,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,BOTH),REPLACE=YES

1 :W:$US123456.TEST.PRIV

A * * * I M P O R T O U T P U T L I S T * * * 10:26:45 11/04/87

/IMPORT TEST.PRIV,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,BOTH),REPLACE=YES

OLD USER-ID CODE NEW USER-ID CODE

FILE HAS BEEN ERASED

FILE NAME

:W:$US123456.TEST.PRIV

(IN)

(OUT)

FSTAT TEST.PRIV

0000024*:W:$US123456.TEST.PRIV

:W: PRIVATE: 1 FILE.

RES= 24, FREE= 20, REL= 18 PAGES

This time, REPLACE=YES is specified in the IMPORT command. As can be seen from the messages, the pubset file TEST.PRIV is erased and replaced by the "private" file

TEST.PRIV.

Return code on SYSOUT: 1

Message on SYSLST:

FILE HAS BEEN ERASED

. (The IMPORT OUTPUT LIST is written to

SYSLST.)

The output from the FSTATUS command shows that TEST.PRIV is stored on private disk ("*" before the path name) and that the new file occupies 2 PAM pages more than the old one (FREE = 20 PAGES).

316

U3586-J-Z125-7-7600

IMPORT

File generation groups

(IN) IMPORT GROUP.PRIV,DEVICE=D3480,VOLUME=WORK02

A * * * I M P O R T O U T P U T L I S T

/IMPORT GROUP.PRIV,DEVICE=D3480,VOLUME=WORK02

* * * 10:35:35

OLD USER-ID CODE NEW USER-ID CODE

FILE DID NOT EXIST

FILE NAME

:W:$US123456.GROUP.PRIV

11/04/87

FILE DID NOT EXIST

:W:$US123456.GROUP.PRIV(*0005)

:W:$US123456.GROUP.PRIV(*0006)

:W:$US123456.GROUP.PRIV(*0007)

:W:$US123456.GROUP.PRIV(*0008)

:W:$US123456.GROUP.PRIV(*0009)

(IN)

(OUT)

FSTAT GROUP.PRIV,GEN=YES

0000000*:W:$US123456.GROUP.PRIV (FGG)

0000003*:W:$US123456.GROUP.PRIV(*0005)

0000003*:W:$US123456.GROUP.PRIV(*0006)

0000003*:W:$US123456.GROUP.PRIV(*0007)

0000003*:W:$US123456.GROUP.PRIV(*0008)

0000003*:W:$US123456.GROUP.PRIV(*0009)

:W: PRIVATE: 6 FILES. RES= 15, FREE= 15, REL= 0 PAGES

The file generation group GROUP.PRIV stored on private disk WORK02 is imported with all of its generations (*5 - *9).

(IN)

FILE GROUP.PRIV(*10),DEVICE=D3480,VOLUME=WORK01

COPY ZE.EXAMP.ER.3,GROUP.PRIV(*10)

FILE GROUP.PRIV(*11),DEVICE=D3480,VOLUME=WORK01

FILE GROUP.PRIV(*12),DEVICE=D3480,VOLUME=WORK01

FILE GROUP.PRIV(*13),DEVICE=D3480,VOLUME=WORK01

COPY ZE.EXAMP.ER.3,GROUP.PRIV(*11)

COPY ZE.EXAMP.ER.3,GROUP.PRIV(*12)

COPY ZE.EXAMP.ER.3,GROUP.PRIV(*13)

(IN) FSTAT GROUP.PRIV,GEN=YES

(OUT) 0000000*:W:$US123456.GROUP.PRIV (FGG)

0000003*:W:$US123456.GROUP.PRIV(*0009)

0000024*:W:$US123456.GROUP.PRIV(*0010)

0000024*:W:$US123456.GROUP.PRIV(*0011)

0000024*:W:$US123456.GROUP.PRIV(*0012)

0000024*:W:$US123456.GROUP.PRIV(*0013)

:W: PRIVATE: 6 FILES. RES= 99, FREE= 95, REL= 84 PAGES

The new generations (*10 to *13) are created on private disk WORK01. The FSTATUS command shows that the file generation group now consists of the generations *9 -

*13.

U3586-J-Z125-7-7600

317

IMPORT

(IN)

(OUT)

FSTAT GROUP.PRIV,GEN=YES,ALL

0000000*:W:$US123456.GROUP.PRIV (FGG)

SHARE = NO ACCESS = WRITE

ACCESS# = 000

RDPASS = NONE

CRDATE = 87-11-04 EXDATE = 87-11-04 LADATE = NONE

WRPASS = NONE EXPASS = NONE

LARGE = NO BACKUP = A VERSION = 000

DESTROY = NO

GEN = 00005

AUDIT

BASE

= NONE

= 00000

DISP = CYCLE

VSN/DEV/EXT = WORK02/D3480

0000003*:W:$US123456.GROUP.PRIV(*0009)

FCBTYPE = NONE

SHARE = NO

VSNTYPE = PVT

ACCESS = WRITE

LASTGN

LASTPG

= 00013

= 0000000

FIRSTGN = 00009

2ND ALLO= 00009

ACCESS# = 000

RDPASS = NONE

VERSION = 000

DESTROY = NO

BLKTYPE = NONE

VSN/DEV/EXT =

EXTCNT = 1

CRDATE = NONE

WRPASS = NONE

AUDIT = NONE

BLKSIZE = 000000

WORK02/D3480/001

EXDATE

EXPASS

LARGE

= NONE

= NO

RECFORM = NONE

LADATE = NONE

BACKUP = A

RECSIZE = 00000

0000024*:W:$US123456.GROUP.PRIV(*0010)

FCBTYPE = SAM

SHARE = NO

VSNTYPE = PVT

ACCESS = WRITE

ACCESS# = 001

RDPASS = NONE

CRDATE

WRPASS

= 87-11-04

= NONE

LASTPG

EXDATE

EXPASS

LARGE

= 0000001

= 87-11-04

= NONE

= NO

2ND ALLO= 00009

LADATE = 87-11-04

BACKUP = A VERSION = 001

DESTROY = NO

BLKTYPE = STD

VSN/DEV/EXT =

EXTCNT = 3

AUDIT = NONE

BLKSIZE = 002048

WORK01/D3480/003

RECFORM = (V,M) RECSIZE = 00000 to save space, the catalog entries for generations *11 to *13 have been omitted here

:W: PRIVATE: 6 FILES. RES= 99, FREE= 95, REL= 84 PAGES

A comparison of the catalog entries shows that the group entry is cataloged on disk

WORK02, which also holds the oldest generation *9. Generation *10 (and generations

*11 to *13) are on disk WORK01.

318

U3586-J-Z125-7-7600

IMPORT

The entire file generation group is deleted from the file catalog.

(IN)

(OUT)

(IN)

(OUT)

(IN)

ERASE ,DEL-OR-EXP,VOLUME=WORK02

% DMS0516 DELETE ALL FILES WITH NOT FULLY QUALIFIED FILENAME

’:W:$US123456.’? REPLY (Y=YES; N=NO)?

ERASE ,DEL-OR-EXP,VOLUME=WORK01

% DMS0516 DELETE ALL FILES WITH NOT FULLY QUALIFIED FILENAME

’:W:$US123456.’? REPLY (Y=YES; N=NO)?

On WORK01, a new group entry GROUP.PRIV with attributes which differ from those of the entry on WORK02 is created.

(IN)

(OUT)

CAT GROUP.PRIV,GEN=3,BASE=12,FIRST=11,DEVICE=D3480,VOLUME=WORK01

FSTAT GROUP.PRIV,ALL

0000000*:W:$US123456.GROUP.PRIV (FGG)

SHARE = NO

ACCESS# = 000

ACCESS

CRDATE

= WRITE

= 87-11-04 EXDATE = 87-11-04 LADATE = NONE

RDPASS = NONE

VERSION = 000

WRPASS = NONE EXPASS = NONE

LARGE = NO BACKUP = A

DESTROY = NO

GEN

DISP

= 00003

= CYCLE

VSN/DEV/EXT =

:W: PRIVATE:

AUDIT

BASE

= NONE

= 00012

WORK01/D3480

1 FILE.

RES=

LASTGN

0, FREE=

= 00012

0, REL=

FIRSTGN = 00011

0 PAGES

Comparison of the two group entries:

GROUP.PRIV

(fields in group entry)

Max. number of generations GEN=

Base value: BASE=

Youngest generation:

Oldest generation:

LASTGN=

FIRSTGN=

WORK01

WORK02

U3586-J-Z125-7-7600

319

IMPORT

With the following IMPORT command, GROUP.PRIV is to be imported in accordance with the group entry on disk WORK01.

(IN)

(OUT)

(IN)

(OUT)

IMPORT GROUP.PRIV,VOLUME=WORK01,DEVICE=D3480,LIST=(YES,BOTH)

2 :W:$US123456.GROUP.PRIV

7 :W:$US123456.GROUP.PRIV(*0010)

0 :W:$US123456.GROUP.PRIV(*0011)

0 :W:$US123456.GROUP.PRIV(*0012)

7 :W:$US123456.GROUP.PRIV(*0013)

FSTAT GROUP.PRIV,GEN=YES

0000000*:W:$US123456.GROUP.PRIV (FGG)

0000024*:W:$US123456.GROUP.PRIV(*0011)

0000024*:W:$US123456.GROUP.PRIV(*0012)

:W: PRIVATE: 3 FILES. RES= 48, FREE= 46, REL= 42 PAGES

As the messages and the FSTATUS command show, only the file generations which match the group entry (*11 and *12) are imported.

The following example shows the effect of an IMPORT command with WORK02 specified in the VOLUME operand: IMPORT of GROUP.PRIV from WORK02 after exporting the newly created GROUP.PRIV from WORK01.

(IN)

(OUT)

(IN)

(OUT)

ER GROUP.PRIV,DEL-OR-EXP,VOLUME=WORK01

IMPORT GROUP.PRIV,VOLUME=WORK02,DEVICE=D3480,LIST=(YES,BOTH)

0 :W:$US123456.GROUP.PRIV

0 :W:$US123456.GROUP.PRIV(*0009)

FSTAT GROUP.PRIV,ALL

0000000*:W:$US123456.GROUP.PRIV (FGG)

SHARE = NO ACCESS = WRITE

ACCESS# = 000

RDPASS = NONE

CRDATE = 87-11-04 EXDATE = 87-11-04 LADATE = NONE

WRPASS = NONE EXPASS = NONE

LARGE = NO BACKUP = A VERSION = 000

DESTROY = NO

GEN = 00005

AUDIT

BASE

= NONE

= 00000

DISP

VSN/DEV/EXT =

:W:

= CYCLE

PRIVATE:

WORK02/D3480

1 FILE.

RES=

LASTGN

0, FREE=

= 00013

0, REL=

FIRSTGN = 00009

0 PAGES

As the IMPORT messages show, the group entry and generation *9 were imported again. The other (missing) generations are then imported with the following IMPORT command -- as shown by the FSTATUS command.

320

U3586-J-Z125-7-7600

IMPORT

(IN)

(OUT)

(IN)

(OUT)

IMPORT GROUP.PRIV,GEN=YES,VOLUME=WORK01,DEVICE=D3480,LIST=(YES,BOTH)

2 :W:$US123456.GROUP.PRIV

0 :W:$US123456.GROUP.PRIV(*0010)

0 :W:$US123456.GROUP.PRIV(*0011)

0 :W:$US123456.GROUP.PRIV(*0012)

0 :W:$US123456.GROUP.PRIV(*0013)

FSTAT GROUP.PRIV,GEN=YES

0000000*:W:$US123456.GROUP.PRIV (FGG)

0000003*:W:$US123456.GROUP.PRIV(*0009)

0000024*:W:$US123456.GROUP.PRIV(*0010)

0000024*:W:$US123456.GROUP.PRIV(*0011)

0000024*:W:$US123456.GROUP.PRIV(*0012)

0000024*:W:$US123456.GROUP.PRIV(*0013)

:W: PRIVATE: 6 FILES. RES= 99, FREE= 95, REL= 84 PAGES

U3586-J-Z125-7-7600

321

INTR

INTR Start interrupt routine for loaded program

Application group: program control (page 30)

Command description

The INTR command effects continuation of an interrupted program run at the address defined in the STXIT macro for the event "communication with the program" (for details on use of STXIT, see the "Executive Macros" manual [5]). If the program does not include an STXIT routine for this "event", the INTR command is rejected with an error message.

Format and operand description

Operation

INTR text

Operands

[text]

Specifies a message which is moved to a buffer in the user program defined by a STXIT macro. If the latter does not specify a buffer, the message is ignored. If no text is supplied, but a buffer has been reserved, then only a null byte is transferred.

The maximum text length is 64 characters. Longer texts are truncated on the right, shorter ones are suffixed by a null byte to denote the end of the text in the user buffer.

Leading and trailing blanks (X’40’) are suppressed. The buffer must begin on a word boundary.

Comments are not permissible in the INTR command as this would be transferred - together with the text specified - to the buffer of the user program.

322

U3586-J-Z125-7-7600

INTR

Example:

For demonstration purposes, a loaded interactive program runs in a loop and consequently keeps issuing the same message via the data terminal:

INTERMEDIATE RESULT 25.

/INTR

HERE STXIT EXIT FOR INTR INTERRUPT

......

(01)

(01) The program is interrupted by pressing the K2 function key (ESCAPE or BREAK) and control passes to system mode. The INTR command causes control to return to the loaded program, not to the break point but to the address of the

STXIT routine which issues a message here.

If the system responds to an INTR command with the message:

%EXC0924 NO OPERATOR ROUTINE IN STXIT; COMMAND IGNORED or

%EXC0923 STXIT NOT INITIALIZED; COMMAND IGNORED.

then the loaded program has no STXIT routine. In this case, you can make use of the

RESUME command, e.g. commence at the start of the program with "RESUME L’0’"

(see the "Interactive Debugging Aid" manual [4]).

U3586-J-Z125-7-7600

323

LOAD

LOAD Load program

Command description

The LOAD command allows you to load programs to memory without initiating them.

The dynamic linking loader (DLL) links object modules and linking load modules (LLM).

The static loader ELDE loads the load modules. For more details, see the "BLS" manual

[22] and "LMS" manual [14].

In order to initiate a loaded program, you must issue the RESUME command.

LOAD is rejected if the file with the linking/load module is protected by a read password which is not entered in the task password list (PASSWORD command).

The loading of programs cannot be nested. If a LOAD command is entered while a program is loaded, this program is unloaded, and the one named in the LOAD command is loaded instead. Although no error flag is set, any ABEND-STXIT routine defined in the unloaded program is activated, unless the LOAD command was called via the CMD macro (see the "Executive Macros" manual [5]).

The EXECUTE command can be used instead of LOAD + RESUME to load and then initiate a program.

Formats and operand descriptions: See EXECUTE command (page 194 and

following pages).

324

U3586-J-Z125-7-7600

LOAD

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

...

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

(OUT)

(IN)

Examples

Example 1

LOAD U.LOAD

% BLS0517 MODULE TICK LOADED.

STA P

NAME

SALEM

RESUME

TSN TYPE C SIZE CURR-CMD PROGRAM-NAME

8550 3 DIALOG 2 1 STA :A:PA123456:U.LOAD

HERE IS TICK

SYSFILE SYSDTA=(SYSCMD)

EXEC $ASSEMB

% BLS0500 PROGRAM ’ASSEMB’, VERSION ’991’ OF ’87-01-15 LOADED.

V29.1X30 OF SIEMENS BS 2000 ASSEMBLER READY

GIVE ASSEMBLER OPTIONS !

*COMOPT SOURCE=S1.SAL.PROG.TICK,ERRFIL,SAVLST,ISD

GIVE ASSEMBLER OPTIONS !

*END HALT

FLAGS IN 00000 STATEMENTS, 000 PRIVILEGED FLAGS, 000 MNOTES

HIGHEST ERROR-WEIGHT : -

(01)

(02) LOAD *,IDA=YES,TIME=10

% BLS0001 DLL VER 915

% BLS0517 MODULE TICK LOADED.

AT FEHL

RESUME

HERE IS TICK

INTERRUPTED AT 000014

(01) The load module in the file U.LOAD is loaded. However processing does not commence until a RESUME command is given.

The memory requirements for this program are taken from the header record of the program. The permitted CPU time is the system default value.

(02) In the language processor run, the source program in the S1.SAL.PROG.TICK file was compiled, and the generated object module with the name TICK was written to the temporary EAM object module file "*". The LOAD command loads the program for a test run which is initially allocated 10 seconds of CPU time. The entry "IDA=YES" guarantees that symbolic addresses, as specified in the source program, can also be used in IDA commands.

U3586-J-Z125-7-7600

325

LOAD

Example 2

If the LOAD command is used to load modules which require resident memory space, then the operand CLASSII must be specified. In interactive mode, you can employ the

"/STATUS BIAS" command (CORE entry) to find out in advance whether the system has enough memory for the resident programs.

/LOAD LOADMOD.1,CLASSII=(6,4,6) (01)

(01) The program LOADMOD.1 requires a total of 6 pages of virtual address space, 4 of which are resident.

326

U3586-J-Z125-7-7600

LOGOFF

LOGOFF Terminate job

Command description

The LOGOFF command is used to terminate a job. The operating system then releases the virtual memory pages and devices used by that job and assigns the system output files to printer or tape.

For newly created file generations, information output to SYSOUT includes the name of the file generation groups concerned, the base value and the first and current generations.

If a LOGOFF command is specified while a program is loaded, any ABEND-STXIT routine that has been defined is activated. This does not apply if the LOGOFF command is called via the CMD macro (see the "Executive Macros" manual [5].

Any monitoring job variable is set to $T.

Format and operand description

Operation

LOGOFF

Operands

[

BUT[,TAPE]

TAPE[,BUT]

BUT[,NOSPOOL]

NOSPOOL[,BUT]

]

BUT

NOSPOOL

This operand applies only to interactive users and is ignored in batch mode. It enables you to indicate that you wish to begin a new job when the current one is terminated and therefore do not want to clear down the existing connection to the terminal. If the BUT entry is omitted, the connection is cleared down.

This operand suppresses output of the system files SYSLST and

SYSOUT (for MSG=H in the LOGON or OPTION command) to the printer, and SYSOPT to the punch. The system files SYSLST and

SYSOUT are not printed out if they are empty at the start of

LOGOFF processing.

U3586-J-Z125-7-7600

327

LOGOFF

TAPE Causes the system files to be spooled out to tape rather than printer.

TAPE is only supported for reasons of compatibility. The

PRINT/PUNCH command should be used for spooling out system files to tape.

Examples

Example 1

(IN)

(OUT)

(IN)

(OUT)

.ABCDEF LOGON PA123456,M1234MON

% JMS066 JOB ABCDEF ACCEPTED ON 91-01-09 AT 16:10, TSN = 9KL0

LOGOFF

% EXC0419 LOGOFF AT 1617 ON 91-01-09, FOR TSN 9KL0

% EXC0421 USED CPU TIME : 1.5425 , SERVICE UNITS: 000003646

(01)

(02)

(01) The job with TSN 9KL0 is terminated at 16.17 on 9 January, 1991.

(02) The amount of CPU time (1.5425 seconds) and number of service units (3646) used by the job are output.

The connection to the terminal is cleared immediately after system message

EXC0421 has been issued.

Example 2

(IN)

(OUT)

LOGOFF BUT

% EXC0419 LOGOFF AT 1624 ON 85-07-29, FOR TSN 9MM4

% EXC0421 USED CPU TIME : 1.6914 , SERVICE UNITS: 000004433

% JMS0150 INSTALLATION ’ H90-P’, BS2000 VERSION ’V100’, HOST

’D123ZE01’: PLEASE ENTER ’SET-LOGON-PARAMETERS’ OR ’?’

The connection to the terminal remains intact. A new LOGON command can be entered immediately.

Example 3

(IN)

(OUT)

LOGOFF

GROUP: :V:$PA123456.GROUP1

BASE: 0000 FIRST: 0001 CURRENT: 0002

% EXC0419 LOGOFF AT 1643 ON 85-07-29, FOR TSN 9922

% EXC0421 USED CPU TIME : 2.0780 , SERVICE UNITS: 000012345

Information on file generation group 1 relating to the base value, first, and current generations is displayed.

328

U3586-J-Z125-7-7600

LOGON

LOGON Initiate job