Macro type: type S (E form/L form/D form/C form/M form) (see "Macro format")
The LFFSNAP macro enables the user to obtain information about files which were saved on a Snapset when a pubset was backed up. The information relates to whether files can be restored (using the RFFSNAP macro or the RESTORE-FILE-FROM-SNAPSET command). The associated pubset must be imported.
Nonprivileged users can obtain information about all files which they can access (as with the FSTAT macro or the SHOW-FILE-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 files of all user IDs. Wildcards are not permitted in the user ID here.
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
PATHNAM
Selects the files which are to be listed.
=<c-string 1..80: filename 1..54 with-wild(80)>
Path name of the file(s) on the Snapset. Wildcards can be used to specify a set of files.
Only files which satisfy the following requirements are listed:
They must be cataloged when the Snapset is created.
The pubset on which they are cataloged must be imported locally.
They may not reside on private disk.
Aliases may be specified. Individual file generations can be specified. When a file generation group is specified, the file generations are also output.
Privileged users (TSOS privilege) can obtain information on the files 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 file(s) is stored.
SNAPSET
This operand may not be specified together with the SNAPID operand.
Specifies the Snapset from which the file 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.
=<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 pubset 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 LFFSNAP 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'40' | X'0535' | Specified file not accessible |
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'0615' | File resident on a volume set which is not available |
X'00' | X'40' | X'0616' | Volume set cannot be accessed on SM pubset |
X'00' | X'40' | X'0622' | Snapset not available |
X'00' | X'40' | X'0624' | File name invalid |
X'00' | X'40' | X'0684' | File does not exist |
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'40' | X'06CC' | No file name matches the wildcard string specified |
X'00' | X'01' | X'06F7' | Invalid operand value |
X'00' | X'01' | X'06FD' | Parameter area invalid or not accessible |
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:
LFFSNAP MF=D,XPAND=PARAM DMALLFPL DSECT , DMALHDR DS 0A DMALFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER DMALIFID DS 0A 0 INTERFACE IDENTIFIER DMALFCTU DS AL2 0 FUNCTION UNIT NUMBER DMALFCT DS AL1 2 FUNCTION NUMBER DMALFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER DMALRET DS 0A 4 GENERAL RETURN CODE DMALSRET DS 0AL2 4 SUB RETURN CODE DMALSR2 DS AL1 4 SUB RETURN CODE 2 DMALSR1 DS AL1 5 SUB RETURN CODE 1 DMALMRET DS 0AL2 6 MAIN RETURN CODE DMALMR2 DS AL1 6 MAIN RETURN CODE 2 DMALMR1 DS AL1 7 MAIN RETURN CODE 1 DMALFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH * DMALPNAM DS CL80 PATHNAM DMALSNAP DS FL1 SNAPIND * SNAPSET - VALUES DMALSNIN EQU 0 SNAPSET=<integer> DMALSNCH EQU 1 SNAPSET=<char> DMALSNLT EQU 2 SNAPSET=*LATEST * DMALSNID DS CL1 SNAPID DMALSNVL DS H SNAPVALUE DMALARAD DS A OUTAREA=(<addr>,...) DMALARLN DS F OUTAREA=(...,<length>) DMAL# EQU *-DMALHDR
Format of the output area
Macro expansion with MF=D and EXPAND=PARAM, and with default values for EQUATES, PREFIX and MACID:
LFFSNAP MF=D,XPAND=OUTPUT
MFTST MF=D,PREFIX=D,MACID=MAL,ALIGN=F,
DMACID=MAL,SUPPORT=(E,D,C,M,L),DNAME=MALOUTL
DMALOUTL DSECT ,
*,##### PREFIX=D, MACID=MAL #####
* Snapset Output
DMALFSIZ DS F FILESIZE
DMALOPNM DS CL54 PATHNAME
DMALSTATE DS FL1 STATE
* STATE = VALUES
DMALSTOP EQU 0 STATE = OPENED
DMALSTCL EQU 1 STATE = CLOSED
DMALSTNR EQU 2 STATE = NOREST
*
DMALFTYPE DS FL1 FILETYPE
* FTYPE = VALUES
DMALFTPB EQU 0 FTYPE = PUBLIC
DMALFTMG EQU 1 FTYPE = MIGRATED
DMALFTFG EQU 2 FTYPE = FGG
DMALFTWR EQU 3 FTYPE = WORK
DMALFTPD EQU 4 FTYPE = PRDISK
DMALFTTP EQU 5 FTYPE = TAPE
DMALFTNT EQU 6 FTYPE = NET
*
*
DMALCRDT DS 0XL16 Creation Date
DMALCRYE DS CL4 YEAR
DMALCRMO DS CL2 MONTH
DMALCRDA DS CL2 DAY
DMALCRHO DS CL2 HOURS
DMALCRMI DS CL2 MINUTES
DMALCRSE DS CL2 SECONDS
DMALCRUS DS CL2 UNUSED
*
*
DMALLCDT DS 0XL16 Last Change Date
DMALLCYE DS CL4 YEAR
DMALLCMO DS CL2 MONTH
DMALLCDA DS CL2 DAY
DMALLCHO DS CL2 HOURS
DMALLCMI DS CL2 MINUTES
DMALLCSE DS CL2 SECONDS
DMALLCUS DS CL2 UNUSED
*
DMALENLT DS FL1 END Indicator
*
DMALSNXT EQU 0 FURTHER ENTRY
DMALSNED EQU 1 LAST ENTRY
DMALSNNS EQU 2 NOT ENOUGH SPACE
*
DMALUNUS DS XL3 UNUSED
DMALOUTPUT# EQU *-DMALFSIZ
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
LFFSNAP MF=D,XPAND=OUTPUT
.
.
MVC LFFSMFC(DMAL#),LFFSMFL
LFFSNAP MF=M,PATHNAM=':X:T.1',PARAM=LFFSMFC,PREFIX=X, *
SNAPSET=-1,OUTAREA=(AREAAD,100)
LFFSNAP MF=E,PARAM=LFFSMFC
.
.
LFFSMFC LFFSNAP MF=C,PREFIX=X,XPAND=PARAM
LFFSMFL LFFSNAP MF=L,PATHNAM='X'
AREA DS CL100
AREAAD DC A(AREA)
.
.