General
Application area: | Starting, interrupting and terminating; see "Starting, interrupting and terminating" |
Macro type: | Type S, MF format 1: standard/L/E/C/D form; see "S-type macros" |
Macro description
The ENTER macro allows the ENTER-JOB command to be issued via the macro command language processor (MCLP) without interrupting program mode (see section “MacroCommand Language Processor macros” (Standard header)). Messages concerning command processing are output to SYSOUT and may additionally be transferred to an area of the calling program. The ENTER-JOB command allows a batch job that is stored in an
(ENTER) file to be transferred to the operating system for processing.
The (ENTER) file is a cataloged file or a library element. The ENTER-JOB command can be issued in both program mode and command mode (see also the “Commands”
manual [19 (Related publications)]). The new job receives its own TSN and is executed in its own task - independently of the calling task. The specifications in the ENTER-JOB command designate the (ENTER) file, identify the caller (access authorization and accounting) and characterize the job and logging for the job run.
The specifications on access authorization are checked against the entry in the user catalog; further specifications regarding the job class and job attributes (job priority, run priority, system resources) are also checked against the entry in the job class definition. These entries may be accessed by the user via the SHOW-USER-ATTRIBUTES or SHOW-JOB-CLASS commands.
If the entries for PRIORITY and NTL (No Time Limit) are not identical in the user catalog and the job class definition, the value that is better for the user is accepted.
The PRIORITY and MSG operands only continue to be supported for reasons of compatibility. Instead, the RUN-PRIO operand - or the RUN-PRIO, START= IMMEDIATELY (for PRIORITY=(p,EXPRESS) and LOG operands together - should be used.
The operand list specified in the command operands must be specified as a string enclosed in single quotes ('pathname [,userid1, ... ,JOB-PAR=..]'). Single quotes that are a part of a string that occurs within this operand list (e.g. specification of the operand HOST='hostid') must be specified twice to prevent them from being interpreted as special characters.
An (ENTER) file begins with the SET-LOGON-PARAMETERS command and ends with the EXIT-JOB command. The operands in the SET-LOGON-PARAMETERS command are not interpreted.
Figure 24: Initiating an ENTER job
Macro format and description of operands
ENTER |
 C /
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The 'pathname' variable stands for: [:catid:] [$userid.] {filename / library(element)}
where:
catid
Catalog ID of the pubset on which the file is stored. Default value: the catalog ID allocated to the user ID in the user catalog.
userid
User ID to which the file is allocated.
Default value: user ID which executes the macro call.
pathname is specified without a catalog ID and user ID and it is not cataloged under the user’s own ID, the system attempts to access a file or library of the same name under the default system ID (“Secondary Read” function, see the “Introductory Guide to DMS” [8 (Related publications)]).filename
Name of the cataloged file with the batch job.
filenamecan also be the name of a temporary file (see the “DMS Introductory Guide” [8 (Related publications)])A file generation or a file generation group cannot be specifiedThe specification of a file group (“file(group)” format) is only permissible for tape filesThe file must be shareable if it does not belong to the own user ID
library
Name of a PLAM library on disk (see the “LMS” manual [29 (Related publications)]).
(member)
Name of the library element with the batch job.
userid1
User ID for the ENTER job to be initiated or *FROMCA if the macro call is issued from a user ID with the OPERATING privilege.
*FROMCA
The user ID of the caller is used.
accountno
Account number for the ENTER job.
userid1 and accountno operands may only be specified or omitted together in the ENTER macro. If they are omitted in the ENTER macro, the values in the SET-LOGON-PARAMETERS command of the executing job are assumed.password
Password for the user ID userid1.
password is a string with a length of 8 bytes (c-string) or 16 bytes (x-string). Because password is a string within a string, the single quotes must be specified twice. The password is not logged on SYSOUT, i.e. it does not appear in the printout of the ENTER job.
If the userid1, accountno and password operands are omitted, they are, in the case of LOGON=YES, taken over from the SET-LOGON-PARAMETERS command of the ENTER file. Otherwise they are taken over from the SET-LOGON-PARAMETERS command of the initiating job.
FROM-LOGON=
Specifies whether or not the operands of the SET-LOGON-PARAMETERS command with which the ENTER file begins are to be evaluated (as with an ENTER-JOB command at the console).
NO
The operands of the SET-LOGON-PARAMETERS command in the ENTER file are not evaluated.
YES
This operand can only be specified from a user ID with the OPERATING privilege.
The operands of the SET-LOGON-PARAMETERS command in the ENTER file are evaluated. However, entries in the ENTER macro have priority, i.e. a value specified in the SET-LOGON-PARAMETERS command becomes effective only if the corresponding operand in the ENTER macro is not specified.
FPASS=
Designates the execute or write password for the ENTER file: write password when ERASE=YES is specified, otherwise the execute password. The operand allows access to the ENTER file if the password specified matches the password that protects this file.
password
Password for accessing the ENTER file. password is a string with a length of 4 bytes (c-string) or 8 bytes (x-string). Because password is a string within a string, the single quotes must be specified twice. The password is not logged on SYSOUT, i.e. it does not appear in the printout of the ENTER job.
CRPASS=
Designates the password with which the ENTER file is encrypted. The operand allows access to the encrypted ENTER file if the password specified matches the password that protects this file.
password
Password for accessing the ENTER file. password is a string with a length of 8 bytes (c-string) or 16 bytes (x-string). Because password is a string within a string, the single quotes must be specified twice. The password is not logged on SYSOUT, i.e. it does not appear in the printout of the ENTER job.
ERASE=
Specifies whether the ENTER file is to be erased when the job is terminated.
NO
The ENTER file is not to be erased when the job is terminated.
YES
The ENTER file is to be erased at the end of the ENTER job.
the file is a library member
the job issuer is not the file’s (co-) owner
the job is abnormally terminated
the job is terminated by an EXIT-JOB (MODE=*ABNORMAL), CANCEL-JOB or SHUTDOWN command
Cases 3. and 4. do not apply to a file on private disk, a temporary file or a file cataloged under the caller's user ID if the ENTER job is to run under a different user ID. In all these cases, the file is deleted once the S.IN. file has been created.
HOST=
Specifies the target system on which the job is to be run.
Only available to users of the software products “HIPLEX MSCF” [26 (Related publications)] and “JV” [22 (Related publications)].
*ANY
The job can run on any target system.
''hostid''
ID of the target system.
jvname1
Job variable containing the host ID. The syntax for jvname1 must comply with the rules for a GETJV operation (see “JV” manual [22 (Related publications)]).
CAT=
Specifies the target system via the specified catalog ID. The job is directed to the system to which the specified catalog is assigned.
Available only to users of the software products “HIPLEX MSCF” [26 (Related publications)] and “JV” [22 (Related publications)].
''catid''
Catalog ID.
jvname2
Job variable containing the catalog ID. The syntax for jvname2 must comply with the rules for a GETJV operation (see “JV” manual [22 (Related publications)]).
JOB-CLASS=
Designates a job class to which the job is to be assigned.
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value *STD.
The authorization for the various job classes can be queried with the SHOW-USER-ATTRIBUTES or SHOW-JOB-CLASS commands.
*STD
The job class is the (standard) job class preset for the user or the system.
jobclass
Name of the job class.
MONJV=
Denotes a job variable that monitors the job.
If the operand is not specified, when FROM-LOGON=YES the value from the SET-LOGON-PARAMETERS command in the ENTER file applies, otherwise the ENTER job is started without MONJV.
Users can address their job via this job variable. During the job run, the operating system allocates the following value to the job variable:
$S | job in job queue |
Only available to users of the “JV” software product [22 (Related publications)].
jvname
Name of the job variable.
JVPASS=
Denotes a password that authorizes access to the monitoring job variable.JVPASS is ignored if MONJV was not specified.
password
Password for the job variable jvname.
password = string with a length of 4 bytes (c-string) or 8 bytes (x-string). Because “password” is a string within a string, the single quotes must be specified twice. The password is not logged on SYSOUT, i.e. it does not appear in the printout of the ENTER job.
JOB-PRIO=
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value STD.
STD
The standard value for the job class is assumed.
jprio
Job priority. MAXIMUM <= jprio <= 9. The lower the value, the higher the job priority (urgency). The value for MAXIMUM is set in the job class definition and can be accessed with the SHOW-JOB-CLASS command.
RERUN=
Specifies whether the job is to be rerun in the next BS2000 session if its execution was interrupted by serious system errors or by the end of the system run.
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value NO.
NO
No rerun of the job.
YES
The job is rerun.
FLUSH=
Specifies whether the job is removed from the job queue if it has not been processed before the end of the system run (SHUTDOWN).
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value NO.
NO
The job remains in the queue. The next system run must be initialized with a warm or selective start.
YES
The job is removed from the queue. Job control with RERUN/FLUSH:
Job control using RERUN/FLASH
if FLUSH=YES and RERUN=YES were specified and the job was interrupted during the previous system run, FLUSH=NO is assumed in the next system run. This ensures that the job remains in the job queue even if it is not started in this system run.
a monitoring job variable is set to $S if the job is repeated.
RERUN and FLUSH are not evaluated if the job is repeated.
FLUSH=YES will be gnored with warning JMS0056 for calendar jobs.
START=
Denotes a time (period of time) for the start of the job.
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value STD.
STD
The standard value for the selected job class is assumed.
SOON
The job is to be started as soon as possible (in line with its priority).
IMMEDIATELY
The job is to be started immediately.
WITHIN(...)
The job is to be started within the specified time (hours/minutes).
0 <= hours <= 23; 0 <= minutes <= 59.
AT(...)
The job is to be started at precisely the specified date and time.
DATE=yy-mm-dd Date (yy = year, mm = month, dd = day)
TIME=hh:mm Time of day (hh = hours, mm = minutes)
Hyphens and colons in DATE= and TIME= must be specified; for example: 31 May 2012 at 15.08 is AT (DATE=12-05-31, TIME=15:08). The following applies to TIME: 00 <=
hh<= 23; 00 <=mm<= 59. If the two-digit year specification is less than 80, it is interpreted as 20yy, entries equal to or greater than 80 are interpreted as 19yy.
EARLIEST(...)
The job is to be started no earlier than at the specified time/date.
|
|
See the START=AT(...) operand.
LATEST(...)
The job is to be started no later than at the specified time (date/time).
|
|
See the START=AT(...) operand.
AT-STREAM-STARTUP
The job is to be started after the startup of the job scheduler.
REPEAT=
Denotes a period of time after which the job is to be started at regular intervals. The repetition is regarded as a job sequence. J(0) denotes the first job run, J(1) denotes the first repetition, ..., and J(n) denotes the nth repetition. The repetition J(i+1) is created with the start of the job J(i), where (i >= 0).
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value STD.
STD
The standard value for the selected job class is assumed.
NO
The job is not repeated.
DAILY
Daily repetition at the time specified with START.
WEEKLY
Weekly repetition at the time specified with START.
PERIOD(...)
Repetition after the specified time interval (in hours and minutes).
0 <= hours <= 23; 0 <= minutes <= 59.
AT-STREAM-STARTUP
Repetition after every startup of the job scheduler.
Notes
Specification of the repeat values NO, DAILY, WEEKLY, PERIOD and AT-STREAM-STARTUP is only valid if they are also authorized in the job class definition; (see the SHOW-JOB-CLASS command).
The RERUN and FLUSH operands are not evaluated if a job is repeated. The job is restarted in the next repetition run.
The ith repetition of a job (i >= 1) is not started until the (i-1)th execution has been terminated.
The abnormal termination of the current job J(i) has no effect on the start of J(i+1); (i >= 0).
Abnormal termination of the complete job: both the job that is currently running J(i) and the subsequent job J(i+1) must be terminated abnormally, (i >= 0);
(CANCEL-JOB command or make the job the last job of the repeat sequence with the command MODIFY-JOB tsn, REPEAT=NO).
CALENDAR=
The start time of the job and any repetitions are specified by a symbolic date, which is defined in a calendar file (calendar job).
The CALENDAR and SYMDATE operands must be specified together.
If CALENDAR and SYMDATE are specified, the START and REPEAT operands cannot be specified.
''pathname''
pathname (see "ENTER - Initiate ENTER job") = name of the calendar file.
SYMDATE=
See CALENDAR.
sym-date-name
Symbolic date, which identifies the start time and any repetitions within the calendar file.
LIMIT=
determines the life of a calendar job. This limit applies in addition to the limits that are set by the calendar.
STD
The life of a calendar job is determined only from the entry of the symbolic date in the calendar.
number
This entry is only valid for calendar jobs.
1 <= number <= 32767
Maximum number of repetitions of the calendar job. Once a single job run has been completed, the run counter is incremented by 1. The system then checks whether the job counter has reached or exceeded the maximum number. If this occurs, the whole calendar job is terminated.
(DATE=yy-mm-dd,TIME=hh:mm)
The entry is only valid for calendar jobs.
Entries in the calendar file are only taken into account up to the specified limit. No further repetition job is generated for calendar entries after the limit; the calendar job terminates.
The limit refers exclusively to the scheduled jobs in the file, not to the real runtime of the jobs. Repetition jobs with a “permissible” start date are not subject to any further restrictions and are, for example, also started after the specified date if it was not possible to start them earlier because of delays in the job scheduler.
The date is determined by specifying the day and time:
See operand START=AT(...)
RUN-PRIO=
Defines the priority for the processing of the job (relative to other tasks).
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value STD.
STD
Standard value for the selected job class. The default value is also accepted if invalid values are specified for “rprio”.
rprio
Specifies the run priority. MAXIMUM <= rprio <= 255. The lower the value, the higher the priority. The value for MAXIMUM is set in both the job class definition and the user catalog and can be accessed with the SHOW-JOB-CLASS or SHOW-USER-ATTRIBUTES command. If the values are not identical, the threshold value that is better for the user is accepted.
TIME=
Denotes the maximum CPU time (in seconds) that the task may use. The maximum amount of CPU time that can be specified is set by the selected job class.
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value STD.
STD
Standard value of the selected job class.
t
CPU time in seconds. 0 <= t <= maximum CPU time.
NTL
No Time Limit. The task runs without a CPU time limit.
PROTECTION=
determines whether the job is protected from being terminated inadvertently by the CANCEL-JOB command.
NONE
The job is not protected.
CANCEL
The job is protected.
PRINT=
Denotes the maximum number of records that can be output by the task (in total) to the SYSLST, SYSLST01, SYSLST02,..., SYSLST99 system files. Data records that are output simultaneously to SYSOUT and SYSLST (LOG=(LISTING=YES) or MSG=FH specification) are not included.
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-LOGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value STD.
STD
Standard value of the selected job class.
number
Number of records. 0 <= number <= MAXIMUM. The value for MAXIMUM is set in the job class definition and can be accessed with the SHOW-JOB-CLASS command.
NO-LIMIT
The number of records is unlimited.
LOG=(...)
Specifies whether the log of the job run is also to be output to SYSLST (LISTING=YES). If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-OGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value *LISTING=NO.
JOB-PAR=
Enables the specification of additional attributes for the selected job class - provided they have been defined and disclosed by the system administration.
If the operand is not specified, when FROM-LOGON=YES it is assigned the value from the SET-OGON-PARAMETERS command in the ENTER file, otherwise it is assigned the value *NO.
*NO
No additional attributes.
''attributes''
String of freely selectable characters; it is allocated by system administration for marking other job class attributes.
PRIORITY=
Designates the priority for the processing of a job (relative to other tasks).
p
Run priority. MAXIMUM <= p <= 255. The lower the value, the higher the priority. The value for MAXIMUM is set both in the job class definition and in the user catalog. It can be accessed with the SHOW-JOB-CLASS or SHOW-USER-ATTRIBUTES command. If the values are not identical, the threshold value that is better for the user is accepted.Default value: standard value for the selected job class.
This standard value is also assumed if invalid values are specified for “p”.
([p],EXP[RESS])
The EXPRESS specification causes the ENTER job to be started immediately. This operand does not effect the further processing of the job. The authorization for the EXPRESS operand is set in the user catalog and/or in the job class definition.
The PRIORITY operand is ignored if the RUN-PRIO operand was specified; the EXPRESS specification is ignored if the START operand was specified.
MSG=
This operand is used to control the way in which system messages are to be output or job execution is to be logged.
F
The full system messages are output to the SYSOUT system file (F for “Full message”).
C
The coded short form of the system messages is output to SYSOUT (C for “Code”).
L
Console messages and operator responses for this job are logged
(L for “Log”). If the user enters MSG=LH, the messages logged to SYSLST are accompanied by the time at which they were entered.
H
Execution is also logged to SYSLST (H for “Hold message”).
addr
Address of the field to which the SYSOUT log is to be written. If omitted, or if the field has a length of zero, the log is output to SYSOUT only. The field must be aligned on a word boundary. Layout:
Bytes 0 - 1: | field length (<= 32767 bytes) |
Bytes 2 - 3: | no entry |
Bytes 4 - n: | start of SYSOUT log. |
The first 4 bytes of each record of the SYSOUT log transferred to the field contain the record length field (bytes 0-1 contain the record length, bytes 2-3 are reserved). The actual output text always starts at byte 4. Output records are written to the field until its boundary is reached. Any further output records that cannot be written to the field are output to SYSOUT only. If the field boundary is reached while a record is being written, the record may be truncated (error flag X'0C').
(r)
Register containing the “addr” address value.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see "S-type macros". The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
PARMOD=
Controls macro expansion. Either the 24-bit or the 31-bit interface is generated.
If PARMOD is not specified here, macro expansion is performed according to the specification for the GPARMOD macro or according to the default setting for the assembler (= 24-bit interface).
24
The 24-bit interface is generated. Data lists and instructions use 24-bit addresses (address space <= 16 Mb).
31
The 31-bit interface is generated. Data lists and instructions use 31-bit addresses (address space <= 2 Gb). Data lists start with the standard header.
Combining the START and REPEAT operands
START | REPEAT | ||
AT-STREAM-STARTUP | DAILY bzw. WEEKLY | PERIOD | |
IMMEDIATELY / SOON | 1. | 3. | 3. |
AT / EARLIEST | 1. | 4. | 6. |
LATEST / WITHIN | 1. | 3. | 7. |
AT-STREAM-STARTUP | 2. | 5. | 5. |
The first job start and all subsequent job starts take place as specified.
The first job start takes place with START=AT-STREAM-STARTUP. All subsequent starts take place after the startup of the job scheduler with START=SOON.
The repetition cycle is based on the moment of job acceptance.
The repetition cycle is based on the specified time (START=...., TIME=....).
The first job start takes place after the startup of the job scheduler. The repetition cycle is based on this start time. Subsequent starts take place with START = SOON.
The repetition cycle is based on the specified time (START=...., TIME=....). The second start and all subsequent starts take place with START=SOON.
The repetition cycle is based on the moment of job acceptance. All subsequent starts take place with START=SOON.
General notes
The operand list of the command operands must be enclosed in single quotes.
A copy of the file is created using the name S.IN.tsn.date.hhmmss in the following cases:
if the file resides on private disk
if the ENTER job is to run under a different user ID than that under which the file is cataloged
if the file is a temporary file
if the file is encrypted
If the ENTER file is a library element, a copy is created under the name
S.IN.libraryname.elementname.tsn.hhmmss.
The S.IN. file is automatically deleted at the end of the job (EXIT-JOB) unless checkpoints were set during job execution (WRCPT macro). In this case, the S.IN. file must be present to ensure a restart without problems (RESTART-PROGRAM command).
Although S.IN. files are password protected (EXEC-PASSWORD) it is possible to erase them with /DELETE-FILE without first entering the password. It is thus possible to remove any S.IN. files that are no longer required or that have not been erased by the system.
ENTER files can be password protected against being read (READ-PASSWORD), overwritten (WRITE-PASSWORD) or executed (EXEC-PASSWORD) (CREATE-FILE command). The EXEC-PASSWORD or a higher-ranking password must be specified in the FPASS operand if an ENTER macro is executed. WRITE-PASSWORD must also be specified if the file is to be erased after execution (ERASE=YES operand).The passwords are checked for errors as soon as the ENTER call is processed. A successful check remains valid even if the user subsequently changes the passwords, and the file is executed.
ENTER files may be SAM or ISAM files with variable record length (RECFORM=V). 72 characters are interpreted for each data record. Where ISAM files are concerned, the key field may be at any position in the data record, since it is masked out. See “Consistent job interface” under the ENTER-JOB command.
Notes on job monitoring (see the “JV” manual [22 (Related publications)])
At ENTER time, the status indicator of “jvname” is set to “$S”, the “TSN” indicator to the job number associated with the job and the processor indicator to the catalog ID of the processor which is executing the job.
If
jvnamecannot be accessed at macro processing time, the call is rejected. If the job variable can only not be accessed later (the ENTER job wishes to enter a value), the job outputs an error message to SYSOUT and continues to run normally.The user ID under which the monitoring job variable is issued and also the user ID for which the job is processed must have access to
jvname.JVPASS is the password, in accordance with the password hierarchy, which allows access to the monitoring job variable. The password must be specified in the ENTER macro if job distribution is required (see the “HIPLEX MSCF” manual [26 (Related publications)]). Without job distribution, the password may be given via a separate ADD-PASSWORD command.
For access to the monitoring job variable, the same rules apply as for access to the ENTER file.
Notes on job distribution (see the “HIPLEX MSCF” manual [26 (Related publications)])
“hostid” must define an active system of the MSCF network, otherwise the ENTER call will be rejected.
“jvname1” must contain the “hostid” of an active system of the MSCF network, otherwise the ENTER call will be rejected.
“catid” must define a known and accessible catalog (within the MSCF network), otherwise the ENTER call will be rejected.
“jvname2” must contain the “catid” of a known and accessible catalog (within the MSCF network), otherwise the ENTER call will be rejected.
If the HOST and CAT operands are specified, the value of the HOST operand is used to define the target system.
All passwords (both FPASS and CRPASS for the ENTER file and JVPASS for the MONJV) must be specified in the ENTER macro when job distribution is required. Without job distribution, the password can also be given using a separate ADD-(CRYPTO-)PASSWORD command.
Return information and error flags
R15:
+---------------+ | | | | | | | | | | | |a|a| +---------------+
A return code relating to the execution of the ENTER macro is transferred in the rightmost byte of register R15.
X'aa' | Meaning |
X'00' | Normal termination. |
X'04' | The request has not been processed due to insufficient memory area. |
X'08' | Error in the operand list (address area). |
X'0C' | The last output record entered in the user area has been truncated. |
X'10' | Macro call/command error (the command returned an error to MCLP), |