MFS Language utility (DFSUPAA0)

Use the MFS Language utility (DFSUPAA0) to create and store the Message Format Service (MFS) control blocks.

The intermediate text block (ITB) form of the control blocks is placed in the IMS.REFERAL library. The control blocks are placed in the IMS.FORMAT library for use during normal IMS operation.

Definition: One format and all the messages that refer to it in their SOR= operand make up a format set.

The MFS Language utility has three modes of operation: standard, batch, and test. In all three modes, the utility is executed offline, accepts the same control statements, and produces the same kinds of ITBs and control blocks. The modes differ in their use of the MFS libraries. Accordingly, they use different procedures.

In standard mode, ITBs written in IMS.REFERAL are converted to control blocks and placed in the staging library, IMS.FORMAT, by the MFSUTL procedure. Because the control blocks are placed in the staging library and not the active library, the standard mode can run concurrently with the online IMS control region.

Batch mode differs from standard mode, in that the MFSBTCH1 procedure places the created control blocks in a special library, IMS.MFSBATCH, for later transfer by the MFSBTCH2 procedure (in another job) to the staging library, IMS.FORMAT.

In test mode, the MFSTEST procedure creates control blocks and places them in a separate IMS.TFORMAT library. The control blocks can be tested without interfering with online operation and can operate concurrently with the online IMS control region.

Stage 2 of IMS system definition generates the following procedures:

MFSUTL: A two-step standard mode execution procedure of the MFS Language utility for creating MFS online control blocks and placing these blocks into the IMS.FORMAT library.
MFSBTCH1: A one-step batch mode execution procedure of the MFS Language utility for creating and accumulating MFS online blocks.
MFSBTCH2: A one-step batch mode execution procedure of the MFS Language utility for placing the accumulated MFS online control blocks (from MFSBTCH1) into the IMS.FORMAT library.
MFSBACK: A two-step execution procedure to back up the MFS libraries. If the optional MFSTEST facility is used, MFSBACK contains an additional step to back up the test library.
MFSREST: A two-step execution procedure to restore the MFS libraries. If the optional MFSTEST facility is used, MFSREST contains an additional step to restore the test library.
MFSRVC: A one-step execution procedure for maintaining the MFS libraries.

If MFSTEST mode is selected during system definition, an additional procedure is generated:

MFSTEST: A two-step test mode execution procedure of the MFS Language utility for creating MFS online blocks and placing them into the IMS.TFORMAT library.

In addition to the procedures for creating new or replacement control blocks, the MFS Language utility includes MFSBACK and MFSREST procedures for backup and restore operations in MFS libraries.

Delete and listing operations are performed by the service utility.

Subsections:

Restrictions
Prerequisites
Requirements
Recommendations
JCL specifications

Restrictions

Do not execute the MFSTEST procedure concurrently with itself or any other program or procedure that utilizes the MFS libraries. To test the control blocks in IMS.TFORMAT, the terminal operator enters the /TEST MFS command. Then, test control blocks from IMS.TFORMAT (as well as online control blocks from the active format library, if necessary) are read into a buffer for test operation. After successful testing, the control blocks can be placed in the staging IMS.FORMAT library by recompiling the source statements using the MFSUTL procedure.

Prerequisites

Currently, no prerequisites are documented for the DFSUPAA0 utility.

Requirements

Currently, no requirements are documented for the DFSUPAA0 utility.

Recommendations

Currently, no recommendations are documented for the DFSUPAA0 utility.

JCL specifications

The DFSUPAA0 utility requires an EXEC statement and DD statements for the MFSUTL, MFSBTCH1, and MFSTEST procedures.

When Step 1 (S1) executes (in the MFSUTL, MFSBTCH1, and MFSTEST procedures), the following parameters can be specified in the PARM keyword of the EXEC statement.

PXREF= NOXREF | XREF: Specifies whether (XREF) or not (NOXREF) a sorted cross reference listing should be provided. The default value is NOXREF. A sorted cross reference listing includes a list of all labels and related references.
PCOMP= NOCOMP | COMP: Specifies whether (COMP or COMPOSITE) or not (NOCOMP) the composite or final version of the statement, after error recovery or substitution has modified it, is printed. The default value is NOCOMP. The composite statement reflects syntactic assumptions made during error recovery. Semantic assumptions do not appear in the composite statement but are reflected in the intermediate text blocks. If the repetitive generation function for MFLD/DFLD statements is used, COMP also causes the generated statements to be printed; NOCOMP suppresses this printing.
PSUBS= NOSUBS | SUBS: Specifies whether (SUBS or SUBSTITUTE) or not (NOSUBS) the substitution variable and its equated value are printed when the substitution variable is encountered in the operand field of a statement. The default value is NOSUBS.
PDIAG= NODIAG | DIAG: Specifies whether (DIAG or DIAGNOSTIC) or not (NODIAG) the XREF, COMP, and SUBS options should all be set on. In addition, diagnostic information is printed. The default value is NODIAG, which has no effect on the XREF, COMP, and SUBS options but suppresses printing of the diagnostic information.
COMPR= NOCOMPRESS | COMPRESS: Specifies whether (COMPRESS) or not (NOCOMPRESS) the IMS.REFERAL library is to be compressed before new ITBs are added. The default value is NOCOMPRESS.
LN= 55 | nn: Specifies how many lines per page should be printed. The default value is 55.
SN= 08 | nn: Specifies the severity code compare value. MSG, FMT, and TABLE blocks whose error severity equals or exceeds this value are not written to the IMS.REFERAL library. The default value is 08.
DEVCHAR= 0 | x: Specifies the alphanumeric suffix character (x) to be appended to DFSUDT0. The name DFSUDT0 identifies the desired device characteristics table. This suffix character (x) corresponds to the value specified in the SUFFIX= keyword of the IMSGEN macro. The default is zero (0).
In the execution of the MFSRVC procedure, one parameter can be specified. The DEVCHAR=0 or x parameter specifies the alphanumeric suffix character (x) to be used for the device characteristics table, when no suffix is specified in the LIST control statement parameter DEVCHAR. The default is zero.

In the execution of Step 2 (S2) in the MFSUTL and MFSBTCH2 procedures, three parameters can be specified in the EXEC statement's PARM keyword:

COMPR2= COMPRESS | NOCOMPRESS: Specifies whether (COMPRESS) or not (NOCOMPRESS) the IMS.FORMAT library is to be compressed before new control blocks are added. The default value is COMPRESS.
COMPR3= COMPREND | NOCOMPREND: Specifies whether (COMPREND) or not (NOCOMPREND) the data set with the ddname of FORMAT is compressed after all format blocks have been added/replaced and the index directory ($$IMSDIR) has been updated.
DIRUPDT= UPDATE | NOUPDATE: Specifies whether (UPDATE) or not (NOUPDATE) the special index directory ($$IMSDIR) is automatically updated after a block has been deleted from a format library. You can bypass the $$IMSDIR update by specifying NOUPDATE. The default is UPDATE.

In the execution of Step 2 (S2) in the MFSTEST procedure, the PARM='TEST' parameter must be specified.

Other EXEC statement parameters that can be specified are:

RGN=: Specifies the region size for this execution. The default is 360K.
SOUT=: Specifies the SYSOUT class. The default is A.
SNODE=: Specifies the node that can be assigned to the MFS utility data set name. The default value is IMS.
SOR=: Specifies the library name that can be assigned to the MFS utility library for SYSIN or SYSLIB. The default value is NOLIB.
MBR=: Specifies the member name that can be assigned to the MFS utility member for SYSIN. The default is NOMBR.

EXEC statement

EXEC statement parameters supported by the MFS Language utility have variable compilation control functions.

The format of the EXEC statement is:

//S1       EXEC PGM=DFSUPAA0,REGION=&RGN,                           
//            PARM=(&PXREF,&PCOMP,&PSUBS,&PDIAG,                    
//            &COMPR,'LINECNT=&LN,STOPRC=&SN',                      
//            'DEVCHAR=&DEVCHAR')

Parameters can be specified on the EXEC statement for the preprocessor and phase 1 to:

Control the printed output
Compress the reference library (IMS.REFERAL)
Request diagnostic information
Indicate which MFS device characteristics table is to be used
Prevent control blocks with a specified level of error from being written in IMS.REFERAL

Parameters can also be specified on the EXEC statement for phase 2 to specify whether IMS.FORMAT and IMS.REFERAL should be compressed and whether $$IMSDIR should be automatically updated after deletions.

The DEVCHAR parameter specifies the suffix of the MFS device characteristics table to be used. The device characteristics table is accessed only if DEV TYPE=3270-An (where n is 1 to 15) is coded as input to the MFS Language utility.

The EXEC statement parameters supported by the MFS Language utility have variable compilation control functions. The parameters that can be specified are:

NOXREF | XREF: Specifies whether (XREF) or not (NOXREF) a sorted cross-reference listing should be provided. A sorted cross-reference listing includes a list of all the labels and related references. The default is NOXREF.
NOCOMP | COMP: Specifies whether (COMP or COMPOSITE) or not (NOCOMP) the composite or final version of the statement, after error recovery or substitution has modified it, will be printed. A composite statement reflects syntactic assumptions made during error recovery. Semantic assumptions do not appear in composite statements but are reflected in the intermediate text blocks. The default is NOCOMP.
NOSUBS | SUBS: Specifies whether (SUBS or SUBSTITUTE) or not (NOSUBS) any statement containing a substitution variable (EQU operand) is printed. The default is NOSUBS.
NODIAG | DIAG: Specifies whether (DIAG or DIAGNOSTIC) or not (NODIAG) the XREF, COMP, and SUBS options should be set on and diagnostic information be printed. The default is NODIAG, which has no effect on the setting of the XREF, COMP, and SUBS options but suppresses printing of the diagnostic information.
NOCOMPRESS | COMPRESS: Specifies whether (COMPRESS) or not (NOCOMPRESS) the IMS.REFERAL library is to be compressed before new ITBs are added. The default is NOCOMPRESS.
DIRUPDT= UPDATE | NOUPDATE: Specifies whether (UPDATE) or not (NOUPDATE) the special index directory ($$IMSDIR) will be automatically updated after one or more blocks have been deleted from a format library. You can bypass the $$IMSDIR update by specifying NOUPDATE. The default is UPDATE.
LINECNT=nn: Specifies how many lines per page should be printed. The default is 55.
STOPRC=nn: Specifies the severity code compare value. MSG, FMT, and TABLE blocks whose error severity equals or exceeds this value will not be written to the IMS.REFERAL library. The default is 08.
DEVCHAR=n | x: Specifies the alphanumeric suffix character (x) used as the final character of the name of the device characteristics table DFSUDT0x loaded when DEV TYPE=3270-An is encountered. The default is zero (DFSUDT00).

The definition statements are described in the sequence shown, with the DO and ENDDO compilation statements where they would normally be coded—before and after the MFLD or DFLD statements. The compilation statement formats are sequenced according to related function (if any)—ALPHA; COPY; EQU and RESCAN (equate processing); STACK and UNSTACK (stacking SYSIN/SYSLIB records); TITLE, PRINT, SPACE, and EJECT (SYSPRINT listing control); and END.

Estimating MFSUTL and MFSTEST region parameters

The following steps help you estimate the main storage requirements that you should specify in the RGN= parameter of the EXEC statement invoking the MFSUTL and MFSTEST procedures.

Calculate statement base count. For the input to the MFS Language utility, determine the largest (number of statements) device format to be processed and the largest message descriptor related to the format. Add the total number of statements contained in these two control blocks to obtain the statement base count.
For the processing of a specific user-supplied MSG or FMT ITB, the utility reprocesses all related MSG or FMT ITBs saved from the IMS.REFERAL data set to ensure compatible linkage between all related online blocks. These reprocessed ITBs must be analyzed as well for the process of obtaining the statement base count.
Estimate Region Requirements. Multiply the statement base count by 214 and add 300000 to the result. Round the resulting value to the next highest multiple of 2048. The result is an estimate of the main storage requirements which should be specified in the RGN= parameter of the EXEC statement invoking the MFSUTL and MFSTEST procedures.
Complex formats with a large number of literal DFLD statements in relation to the statement base count can exceed the estimate.

DD statements

The data set names used in the MFSUTL, MFSBTCH1, MFSBTCH2, and MFSTEST procedures fit installation needs. The ddnames used and the data sets they refer to are:

REFIN
REFOUT
REFRD: Refers to the MFS reference library, except when used in the MFSTEST procedure. In MFSTEST, REFIN and REFRD refer to the MFS reference library; REFOUT is a temporary data set.
FORMAT: Refers to the MFS control block library. In MFSTEST, this ddname refers to the MFS test control block library.
SYSLIB: Refers to an optional user library from which input can be copied.
SYSIN: Refers to the input data set, which can be a sequential data set or a member of a partitioned data set.
DUMMY: Refers to the IMS procedure library, which contains control statements used to compress the MFS reference and control block libraries.
SYSUT3
SYSUT4: Are ddnames for data sets used during the data set compression as work data sets.

DUMMY, SYSUT3, and SYSUT4 can all be omitted if neither the MFS reference library nor the MFS control block library is to be compressed.

UTPRINT: Is used for messages during the compression of the MFR reference library, and is used for MFS error and status messages during MFS Language utility Phase 2 processing.

The following ddnames refer to data sets used in the MFSRVC procedure. The data set names can be altered to fit installation needs.

REFIN: Refers to the MFS reference library.
FORMAT: Refers to the MFS control block library.
SYSIN: Refers to the input data set, which can be a sequential data set or a member of a partitioned data set.
SYSSNAP: Refers to a data set that is used to receive the output from a SNAP macro if certain severe errors are detected.
SYSPRINT: Refers to the destination of the output. If output is to be sent to a data set (instead of SYSOUT=), use DISP=MOD for the data set.