Macro type: type S (E form/L form/D form/C form/M form) (see "Macro format")
The LJFSNAP macro enables the user to obtain information about job variables which were saved on a Snapset when a pubset was backed up. The information relates to whether job variables can be restored (using the RJFSNAP macro or the RESTORE-JV-FROM-SNAPSET command). The associated pubset must be imported.
Nonprivileged users can obtain information about all job variables which they can access (as with the FSTAT macro or the SHOW-JV-ATTRIBUTES command, which supplies information from the current file catalog).
Information on all existing Snapsets of a pubset can be obtained using the SHOW-SNAPSET-CONFIGURATION command.
The Snapsets are temporarily not available if the SHC-OSD subsystem was not active when the pubset was imported. In this case the command is aborted with return code 0622. As soon as SHC-OSD is active, the Snapsets are subsequently activated when the SHOW-SNAPSET-CONFIGURATION command is called.
Privileged functions
Systems support (TSOS privilege) can obtain information on the job variables of all user IDs. Wildcards are not permitted in the user ID here.
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
JVNAME
Selects the job variables which are to be listed.
=<c-string 1..80: filename 1..54 with-wild(80)>
Path name of the job variables on the Snapset. Wildcards can be used to specify a set of job variables.
The job variables must satisfy the following requirements:
They must be cataloged when the Snapset is created.
The pubset on which they are cataloged must be imported locally.
Aliases may be specified.
Privileged users (TSOS privilege) can obtain information on the job variables of all user IDs. Wildcards are not permitted in the user ID here.
=<var: char:80>
Only possible with MF=M:
Symbolic address of a memory area of 80 bytes in which the path name or wildcard string for the required job variable(s) is stored.
SNAPSET
This operand may not be specified together with the SNAPID operand.
Specifies the Snapset from which the job variable information is to be output by means of the relative age.
=<integer -52..-1>
Specifies the Snapset explicitly by means of the relative age. The value -1 specifies the latest Snapset (also corresponds to *LATEST).
=*LATEST
The information from the latest Snapset (i.e. from the most recent pubset backup) is output.
SNAPID
This operand may not be specified together with the SNAPSET operand.
Specifies the Snapset from which the file information is to be output by means of the Snapset ID.
=<c-string 1..1: name 1..1 with-low>
Specifies the Snapset explicitly by means of the Snapset ID. The maximum of 52 Snapsets for a pubsets are distinguished by means of Snapset IDs specified which comprise letters from the 26 lowercase letters a to z and the 26 uppercase letters A to Z.
=<var: char 1..1>
Only possible with MF=M:
Symbolic address of a memory area of 1 byte in which the Snapset ID is stored.
Note
If neither SNAPSET nor SNAPID is specified, the information from the latest Snapset is output.
OUTAREA
Specifies the output area in which the information is to be stored.
=(<var: pointer>,<integer 0..32767>)
Specifies the address and length of the output area.
EQUATES
Control operand; for MF=C and MF=D only:
Specifies whether equates are also to be generated for the values of the fields of the parameter or output area when the parameter or output area is expanded.
= *YES
When the parameter or output area is expanded, equates are also generated for the values of the fields of the parameter or output area.
= *NO
When the parameter or output area is expanded, no equates are generated for the values of the fields of the parameter or output area.
XPAND
Control operand; for MF=C and MF=D only:
Defines which structure is to be expanded (i.e. generated). This operand is ignored for other MF values.
= PARAM
Expands the layout of the parameter list.
= OUTPUT
Expands the layout of the output area.
Return codes
The return code is placed in the standard header of the parameter area. The parameter area may then not be located in the read-only area, otherwise the program terminates.
Standard header: ccbbaaaa
The following code relating to execution of the LJFSNAP macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'00' | X'0000' | No error |
X'00' | X'40' | X'0501' | Requested catalog not available |
X'00' | X'40' | X'0505' | Error in host communication |
X'00' | X'40' | X'0512' | Requested catalog not found |
X'00' | X'40' | X'051B' | Requested user ID not on the pubset |
X'00' | X'40' | X'051D' | LOGON password different on specified pubset |
X'00' | X'20' | X'0531' | Unexpected error during catalog access |
X'00' | X'82' | X'0594' | Not enough virtual memory |
X'00' | X'01' | X'05AB' | Address of output area incorrect/not specified |
X'02' | X'00' | X'05B6' | Incorrect time conversion in GTIME macro |
X'00' | X'20' | X'05C7' | Internal error in DMS |
X'00' | X'40' | X'05FC' | Specified user ID not on home pubset |
X'00' | X'40' | X'0622' | Snapset not available |
X'00' | X'40' | X'0624' | JV name invalid |
X'00' | X'40' | X'0682' | JV error when accessing JV |
X'02' | X'00' | X'06CB' | Output information not transferred in full |
X'00' | X'01' | X'06CB' | Output area too small |
X'00' | X'01' | X'06F7' | Invalid operand value |
X'00' | X'01' | X'06FD' | Parameter area invalid or not accessible |
The return codes with the maincode X’04xy’ belong to the component JVS. A list which
includes the meanings can be output using the JVSERROR macro (see also the “Job Variables” manual [21]).
Further return codes, whose meanings are defined by conventions valid for all macros, can be found in the table on "Standard header" (standard header).
The calling program is terminated if one of the following errors occurs with respect to the parameter list:
the list is not assigned to the caller
the list is not aligned on a word boundary
the list is write-protected.
Layout of the operand list
Macro expansion with MF=D and EXPAND=PARAM, and default values for EQUATES, PREFIX and MACID:
LJFSNAP MF=D,XPAND=PARAM DMAJLFPL DSECT , DMAJHDR DS 0A DMAJFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER DMAJIFID DS 0A 0 INTERFACE IDENTIFIER DMAJFCTU DS AL2 0 FUNCTION UNIT NUMBER DMAJFCT DS AL1 2 FUNCTION NUMBER DMAJFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER DMAJRET DS 0A 4 GENERAL RETURN CODE DMAJSRET DS 0AL2 4 SUB RETURN CODE DMAJSR2 DS AL1 4 SUB RETURN CODE 2 DMAJSR1 DS AL1 5 SUB RETURN CODE 1 DMAJMRET DS 0AL2 6 MAIN RETURN CODE DMAJMR2 DS AL1 6 MAIN RETURN CODE 2 DMAJMR1 DS AL1 7 MAIN RETURN CODE 1 DMAJFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH * DMAJJVNM DS CL80 JVname DMAJSNAP DS FL1 Snapind * SNAPSET - VALUES DMAJSNIN EQU 0 SNAPSET=<integer> DMAJSNCH EQU 1 SNAPSET=<char> DMAJSNLT EQU 2 SNAPSET=*LATEST * DMAJSNID DS CL1 Snapid DMAJSNVL DS H SnapValue DMAJARAD DS A Outarea=(<addr>,...) DMAJARLN DS F Outarea=(...,<length>) DMAJ# EQU *-DMAJHDR
Format of the output area
Macro expansion with MF=D and EXPAND=PARAM, and with default values for EQUATES, PREFIX and MACID:
LJFSNAP MF=D,XPAND=OUTPUT DMAJOUTL DSECT , * Output List DMAJJSIZ DS F JVSIZE DMAJOJVN DS CL54 JVNAME DMAJUNU1 DS XL2 UNUSED * DMAJCRDT DS 0XL16 Creation Date DMAJCRYE DS CL4 YEAR DMAJCRMO DS CL2 MONTH DMAJCRDA DS CL2 DAY DMAJCRHO DS CL2 HOURS DMAJCRMI DS CL2 MINUTES DMAJCRSE DS CL2 SECONDS DMAJCRUS DS CL2 UNUSED * * DMAJEXDT DS 0XL16 Expiration Date DMAJEXYE DS CL4 YEAR DMAJEXMO DS CL2 MONTH DMAJEXDA DS CL2 DAY DMAJEXHO DS CL2 HOURS DMAJEXMI DS CL2 MINUTES DMAJEXSE DS CL2 SECONDS DMAJEXUS DS CL2 UNUSED * DMAJENLT DS FL1 END Indicator * DMAJSNXT EQU 0 FURTHER ENTRY DMAJSNED EQU 1 LAST ENTRY DMAJSNNS EQU 2 NOT ENOUGH SPACE * DMAJUNU2 DS XL3 UNUSED DMAJOUTPUT# EQU *-DMAJJSIZ
The following cases are distinguished when the Snapset information is output to the user’s output area:
All the information could be output
The output area is overwritten with the required information, the caller receives return code 0. The output area is not deleted to the end, but only written as far as necessary.
No files match the selection criteria
The output area is not written at all. The caller receives return code 0684 or 06CC (in the case of wildcards/partial qualification).No output was possible
The output area could not be written (return code 05AB after validation of the output area or address) or it is too small to transfer output information (return code 06CB).Complete output was not possible
Some file information blocks could not be transferred. In addition to the associated display in the output area (NOT ENOUGH SPACE), return code 06CB with subreturn code2 X'02' is output.
Sample calling sequence
LJFSNAP MF=D,XPAND=OUTPUT
.
.
MVC LJFSMFC(DMAL#),LJFSMFL
LJFSNAP MF=M,PREFIX=X,JVNAME=':X:JV.1',OUTAREA=(AREAAD,100), *
PARAM=LJFSMFC
LJFSNAP MF=E,PARAM=LJFSMFC
.
.
LJFSMFC LJFSNAP MF=C,PREFIX=X,XPAND=PARAM
LJFSMFL LJFSNAP MF=L,PATHNAM='X'
AREA DS CL100
AREAAD DC A(AREA)