The message statements define the MID and MOD control blocks and hierarchically consist of the following statements:
MSG-----------Defines either a MID or MOD
LPAGE--------omitted if logical paging is not required
PASSWORD----Defines password fields in following
MFLD statements, optional
MFLD-----A password field, program will not get
This as it is processed by IMS and is
Stripped off
MFLD-----Another password field
.
SEG---------Defines first message segment
MFLD-----Defines message data fields which will be
contained in messages sent to and from
IMS
MFLD-----Another field
.
.
SEG---------Defines 2nd message segment (optional)
MFLD-----Defines message data for this segment
MFLD-----Another field
.
.
LPAGE--------omitted if logical paging is not required
PASSWORD----Defines password fields in following
MFLD statements, optional
MFLD-----A password field, program will not get
This as it is processed by IMS and is
Stripped off
MFLD-----Another password field
.
SEG---------Defines first message segment
MFLD-----Defines message data fields which will be
contained in messages sent to and from
IMS
MFLD-----Another field
.
.
SEG---------Defines 2nd message segment (optional)
MFLD-----Defines message data for this segment
MFLD-----Another field
.
.
MSGEND---------Defines the end of either a MID or MOD |
The MSG statement defines either a MID or MOD. Below figure shows the various parameters associated with a MSG statement.
------------------------------------------------------------------------
COLUMNS
****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77
1 0 6 0 0 0 0 0 12
------------------------------------------------------------------------
label MSG {TYPE={INPUT or OUTPUT},} X
SOR=(format name<,IGNORE>), X
{OPT={1 or 2 or 3},} X
{NXT=message statement name}<,> X
..... the additional parameters below are valid for TYPE=OUTPUT only..
{PAGE={NO or Yes}}, X
{FILL={C‘ ’or C‘c’ or NULL or PT}} |
This is required alphanumeric name that is used by the MFS utility to construct the control block (MID or MOD) member name in the format library. This may also be the message statement name referenced by the optional NXT=parameter of another message descriptor.
The EDS User's Guide Volume 5 naming conventions for the label are the following:
Character(s) 1-3 - Contains the account or system code.
Character(s) 4 - Depends on whether a MID or MOD. (Contains an I if this is a MID, an O if this is a MOD).
Character(s) 5-8 - User or account assigned.
Note: Be careful to keep the labels unique within an IMS system. The label is the only way that MFS knows which control block to use.
This parameter identifies whether the message is a MID or MOD. When coding a MID, specify TYPE=INPUT. For a MOD, specify TYPE=OUTPUT. It is an optional parameter when coding the MID because the default is TYPE=INPUT.
This parameter points to the device format statement, which defines the device and data fields that will be processed by the message descriptor. The format name is the label name associated with the FMT statement. (See Device Statements for more detail on the FMT statement.) If the IGNORE is specified for TYPE=OUTPUT, MFS will use fields for the device with FEAT=IGNORE. (See DEV-Device Characteristics for more detail on the FEAT=option.) Only specify IGNORE for TYPE=INPUT if the corresponding MOD specified IGNORE.
Note: Since you will typically see FEAT=IGNORE on the device FMT statements, we will code IGNORE in this course.
This parameter specifies the MFS formatting option to be used for message editing. Since Option 1 offers a standard MFS formatting of messages, it is used in this course and workshops. The other options allow for data compression within the message, and are not commonly used because the use of options other than OPT=1 will increase the program complexity. OPT=1 is the default. Refer to the IMS/VS Message Format Service User's Guide, or IMS/VS Version Message Format Service User's Guide for details on the other MFS format options.)
This parameter indicates the next message descriptor to be used as a result of message processing. This means that a MID can point to a MOD, or a MOD to a MID, by specifying the message statement name (or MSG label name) for the NXT option. PAGE This parameter specifies whether (YES) or not (NO) operator logical paging (forward and backward) is to be used for the MOD. (See Logical Pages for more detail on logical paging. Refer to the IMS/VS Message Format Service User's Guide, or IMS/VS Message Format Service User's Guide for details on how to use this option for both logical and physical paging.) Note: Since this course does not teach logical paging, we will use PAGE=NO in all workshops. (The default for this parameter is PAGE=NO, so it is not required in TYPE=OUTPUT source.)
This parameter specifies whether (YES) or not (NO) operator logical paging (forward and backward) is to be used for the MOD. (See Logical Pages for more detail on logical paging. Refer to the IMS/VS Message Format Service User's Guide, or IMS/VS Message Format Service User's Guide for details on how to use this option for both logical and physical paging.) Note: Since this course does not teach logical paging, we will use PAGE=NO in all workshops. (The default for this parameter is PAGE=NO, so it is not required in TYPE=OUTPUT source.)
Note: Since this course does not teach logical paging, we will use PAGE=NO in all workshops. (The default for this parameter is PAGE=NO, so it is not required in TYPE=OUTPUT source.)
This parameter specifies the fill character to be used for output fields.
FILL=C'c' will cause the character specified to be used as fill in each of the output device fields. FILL=C' 'is the default.
FILL=NULL means that the output device fields are not to be filled.
FILL=PT. After placing the data from the MOD into the output device field, if it does not fill the device output field, a tab character will be placed at the end of the data, which causes the rest of the device output field to be cleared.
Remember, if the FILL= is used on the MOD, the DPAGE must specify FILL=NONE. Since we coded FILL=PT on the DPAGE, we do not need to code a FILL parameter here. For our example format we will code the MID first, followed by the MOD. This is done since the MID defines the input message sent into IMS, then the MOD defines the output message sent from IMS.
For our example format we will code the MID first, followed by the MOD. This is done since the MID defines the input message sent into IMS, then the MOD defines the output message sent from IMS.
------------------------------------------------------------------------ COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 ------------------------------------------------------------------------ ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT |
The SEG statement defines message segments (pieces of the same message, not to be confused with data base segments). It is an optional statement and is needed only for multi-segmented messages. In this course, we will address only single segment messages because that is what you will encounter most on your account. Although the SEG statement is optional, if you do not code one, MFS will generate one at assembly time and give a return code of RC 0004. This course recommends coding the SEG statement for the sake of readability, consistency, and debugging ease.
In addition, the Performance Factor section of the MFS Guide recommends that the number of segments in a message be minimized. Below figure describes the coding of a SEG statement.
------------------------------------------------------------------------
COLUMNS
****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77
1 0 6 0 0 0 0 0 12
------------------------------------------------------------------------
label SEG |
This is an optional alphanumeric name that can be used to identify multiple segments in a message. When only one SEG statement is coded, a label is typically omitted.
This defines the beginning of a message segment. Only single segment messages are used for this course.
Our example format now looks like the following with the SEG statement added.
------------------------------------------------------------------------
COLUMNS
****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77
1 0 6 0 0 0 0 0 12
------------------------------------------------------------------------
ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT
SEG |
The MFLD statement defines how the data fields will be transmitted to and from the application program. Every MSG statement must have at least one MFLD statement.
Note: Typically, each MFLD maps to a field on the device. (Remember the DFLD's and their labels.) However, it is not a requirement that every MFLD maps to a DFLD. If your MFLD references a DFLD label, that label must exist or a return code of RC 0004 will be returned.
Below figure shows the MFLD statement structure.
------------------------------------------------------------------------
COLUMNS
****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77
1 0 6 0 0 0 0 0 12
------------------------------------------------------------------------
--- the parameters below are for Type-INPUT only .....
label MFLD {(dfldname,‘literal’) or dfldname or ‘literal’) X
LTH=nn, X
JUST={L or R}, X
ATTR={NO or YES}, X
FILL={X‘40’ OR X‘nn’ or C‘c’ or NULL}
.....the parameters below are for TYPE=OUTPUT only ....
label MFLD {(dfldname,‘literal’) or dfldname or X
(dfldname,system-literal)}, X
LTH=nn, X
JUST={L or R), X
ATTR={NO or YES} |
This is an optional label that can be used to help document the field in the message descriptor. It can be from one to eight alphanumeric characters long.
This is the device field name that this message field maps to. The device field name is the label attached to the DFLD statement (described earlier). If using a DFLD, think of it as either the source of the data for this MFLD (in the case of a MID), or the screen destination for the data contained in the MFLD (in the case of a MOD). You will have an MFLD for every field you wish to have contained in the message to and from your application program, as well as any system literals (in the MOD only) you want displayed on the screen. If you use dfldname, ‘literal' for an MFLD in the MID, and the dfldname does not contain any data, the literal is placed into the MFLD. If you use (dfldname, literal')) for an MFLD in the MOD, the literal is placed in dfldname referenced. Do not allocate space in the MOD from program when using this form.
This is a literal value to be inserted in the message. This is used mainly to have the transaction code inserted as part of a message to send default data to a program. The literal length cannot exceed 256.
You can include system literals only for output messages. These literals are generated prior to the device receiving the message. You cannot specify ATTR, LTH, or JUST with system literals. System literals include the following:
DATE1 - 6 bytes - YY.DDD format
DATE2 - 8 bytes - MM/DD/YY format
DATE3 - 8 bytes - DD/MM/DD format
DATE4 - 8 bytes - YY/MM/DD format
TIME - 8 bytes – HH:MM:SS format
This parameter specifies the length of the message field. The range is from 1 to 8000 bytes. The length is optional, if a literal specified. If LTH is specified for a literal, the field will either be padded or truncated. If omitted for a literal, MFS determines the length.
This specifies if the data is to be right (R) or left (L) justified within the message field. This also implies truncation right or left. A right-justified field is truncated on the left. A left-justified field is truncated on the right. The default setting is left-justification.
This parameter determines if the 3270 attributes can be modified by the application program. If YES is specified, you must include an extra two bytes in the LTH parameter for the field. These represent the attribute bytes. The I/O area in your application program for the MID and / or MOD must account for not only the actual length of the field, but also the extra two attribute bytes preceding each field. If NO is specified, the LTH parameter specifies the actual length of the field, and no attribute bytes need to be considered in the application program I/O area for the MID/or MOD. When NO is specified, the application program cannot change the attributes of the field displayed on the device.
If ATTR=YES is specified for an MFLD on a MID, MFS will fill the two attribute bytes with blanks prior to putting the message into the message queue.
Note: This course recommends only using ATTR=YES for MFLD’S in the MOD.
The FILL parameter is for input message fields only. It is used to specify a fill character for padding when the data from the device (DFLD) is less than the length specified for the MFLD.
X ‘nn’ means that the character representative of the hex field will be used to pad the input MFLD. The default fill value is X'40'.
C'c' means that the character specified will be used to pad the input MFLD.
NULL means the field will be compressed to the left by the amount of the missing data. If there is no data present, the field is compressed completely. Note that this can cause positions of fields in the input message to shift!.
MSGEND Message End |
The last message statement is the MSGEND, and denotes the end of a MSG, which means the end of a MID or MOD. Below figure shows the MSGEND statement structure.
------------------------------------------------------------------------
COLUMNS
****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77
1 0 6 0 0 0 0 0 12
------------------------------------------------------------------------
MSGEND |
Let's continue to code our example format. First we must determine what fields we need in the application program. These will be the MFLD’S that make up the MID. We need to discuss what would happen to our message when the ENTER key or a PF is pressed.
When we talked about how messages are sent to and from application programs, it was stated that IMS looks at the beginning of each message (MID) to determine what to do.
These are the three types of messages that can be sent from a terminal:
If the first byte is a slash (/), IMS interprets the message as an IMS operator command.
If the first eight or less bytes followed by a space reference a logical terminal (LTERM), the message following is directed to that device. A logical terminal is also referred to as a logical device, as it does not actually have to be a terminal.
If the first eight or less bytes, followed by a space reference a transaction code, the corresponding application program is scheduled for execution and the message is sent to the transaction queue for processing.
In our example, the client wanted PF2 to cause a transaction to be started (ABCPSTPT), PF3 to return to a menu, modname ABCOMENU, and the ENTER key to schedule our transaction (ABCPSTAT). Depending on whether a PF is pressed or not, we must ensure that we have a valid message created. Remember, the MID will always be the sum of all MFLD’S we have coded.
Let's see how the fields will be defined for our MID.
------------------------------------------------------------------------
COLUMNS
****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77
1 0 6 0 0 0 0 0 12
------------------------------------------------------------------------
ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT
SEG
MFLD (PFKEYSOO,'ABCPSTAT '),LTH=14,JUST=L,ATTR=NO 1
MFLD ITEMNUM,LTH=06,JUST=R,ATTR=NO,FILL=X'40' 2
MSGEND |
That concludes defining our MID.
This input MFLD is used to define the first 14 bytes of the message. If a pre-defined PF is pressed, the literal assigned to the PF on the DEV statement of the FMT is placed in the first 14 bytes. The dfldname PFKEYSOO is the name assigned on the DEV statement. The length of the MFLD is determined by the longest PF literal. If a pre-defined PF is not pressed, the literal is assigned to the MFLD.
This MFLD shows how an input data field is coded for a MID. With ATTR=NO, you do not include the two attribute bytes as part of the length. FILL=X'40' will cause blanks to be placed in the field if the client does not type any data into the DFLD ITEMNUM prior to pressing the ENTER key.
Let's continue to code our example format. We need to determine what fields will be sent by the application program. We may want to change the attributes of the fields (for instance, add high intensity). In addition, a couple of system literals will be supplied by MFS. The system literals can be placed anywhere in the MOD but it is best of place them in the beginning of the end. Let’s code the MOD and add the source to our MID.
------------------------------------------------------------------------
COLUMNS
****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77
1 0 6 0 0 0 0 0 12
------------------------------------------------------------------------
ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT
SEG
MFLD (PFKEYSOO,'ABCPSTAT '),LTH=14,JUST=L,ATTR=NO
MFLD ITEMNUM,LTH=06,JUST=R,ATTR=NNO,FILL=X'40'
MSGEND
ABCOSTAT MSG TYPE=OUTPUT,SOR=(ABCSTA,IGNORE),OPT=1,PAGE=NO, X
NXT=ABCISTAT 1
SEG
MFLD (SYSDATE,DATE2) 2
MFLD (SYSTIME,TIME) 2
MFLD ITEMNUM,LTH=08,JUST=R,ATTR=YES 3
MFLD STCODE,LTH=03,JUST=L,ATTR=YES
MFLD STDTIN,LTH=08,JUST-L,ATTR=YES
MFLD STDTOUT,LTH=08,JUST=L,ATTR=YES
MFLD STDESC,LTH=22,JUST=L,ATTR=YES
MSGEND
END 4 |
The additional points of interest are also indicated by a string of periods followed by a number. These comments are not coded in the format.
This NXT=points logically to the MOD label, and the NXT=in the MOD points to the MID label. This will be discussed further in the IMS Online coding section.
These MFLD’S define the system literal DATE2 (in MM/DD/YY format) and the system literal for TIME (format HH:MM:SS). The actual date and time are not part of the message data returned from the program. They are provided by MFS when the DOF and MOD are combined to create the final formatted screen for the client.
This MFLD represents how each data field is typically coded in a MOD. Notice that in the MOD, ATTR=YES is coded for output fields where the application program requires the ability to change attribute settings. As with the MID MFLD statements, when ATTR=YES, you must increase the logical length of the field by two bytes.
The END statement is for the Assembler Language to indicate the end for the source code.
The completed MFS (including comments and proper documentation) is shown below. Be sure to follow any additional account standards when creating MFS source at your account.
------------------------------------------------------------------------
COLUMNS
****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77
1 0 6 0 0 0 0 0 12
------------------------------------------------------------------------
PRINT NOGEN 1
ABCSTA FMT
DEV TYPE=32700A2,FEAT=IGNORE,PFK=(PFKEYSOO, X
2=‘ABCPSTPT’ X
3=‘/FOR ABCOMENU.’)
DIV TYPE=INOUT
DPAGE CURSOR=((06,38)),FILL=PT
DFLD ‘ABCPSTAT’,POS=(01,2),ATTR=(NUM,PROT,HI)
DFLD ‘ABC RENTAL COMPANY’,POS=(01,26), X
ATTR=(ALPHA,PROT,HI)
DFLD ‘ABCOSTAT’,POS=(01,56),ATTR=(ALPHA,PROT,HI)
DFLD ‘DATE:’,POS=(02,2),ATTR=(ALPHA,PROT,HI)
SYSDATE DFLD POS=(02,8),LTH=8,ATTR=(ALPHA,PORT,NORM)
DFLD ‘STATUS DISPLAY’,POS=(02,28),ATTR=(ALPHA,PROT,HI)
DFLD ‘TIME:’,POS=(02,56),ATTR=(ALPHA,PROT,HI)
SYSTIME DFLD POS=(02,62),LTH=08,ATTR=(ALPHA,PROT,NORM)
DFLD ‘ITEM NUMBER:’,POS=(06,25),ATTR=(ALPHA,PROT,HI)
ITEMNUM DFLD POS=(06,38),LTH=06,ATTR=(NUM,NOPROT,NORM,MOD)
DFLD ‘(PF2 - PRINT STATUS HISTORY)’,POS=(08,24), X
ATTR=(NNM,PROT,HI)
DFLD ‘(PF3 - RETURN TO MENU)’,POS=(09,24), X
ATTR=(ALPHA,PORT,HI)
DFLD ‘========================================================
===========’,POS=(10,2),ATTR=(ALPHA,PROT,HI)
DFLD ‘STATUS CODE:’,POS=(11,02),ATTR=(ALPHA,PROT,HI)
STCODE DFLD POS=(11,15),LTH=01,ATTR=(ALPHA,PROT,NORM)
DFLD ‘STATUS DATE IN:’,POS=(11,19),ATTR=(ALPHA,PROT,HI)
STDTIN DFLD POS=(11,35),LTH=06,ATTR=(ALPHA,PROT,NORM)
DFLD ‘STATUS DATE OUT’,POS=(11,44),ATTR=(ALPHA,PROT,HI)
STDTOUT DFLD POS=(11,61),LTH=06,ATTR=(ALPHA,PROT,NORM)
DFLD ‘STATUS DESCRIPTION: ’,POS=(13,02), X
ATTR=(ALPHA,PROT,HI)
STDESC DFLD POS=(13,22),LTH=20,ATTR=(ALPHA,PROT,NORM)
FMTEND
ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT
SEG
MFLD (PFKEYSOO,'ABCPSTAT '),LTH=14,JUST=L,ATTR=NO
MFLD ITEMNUM,LTH=06,JUST=R,ATTR=NNO,FILL=X'40'
MSGEND
ABCOSTAT MSG TYPE=OUTPUT,SOR=(ABCSTA,IGNORE),OPT=1,PAGE=NO, X
NXT=ABCISTAT
SEG
MFLD (SYSDATE,DATE2)
MFLD (SYSTIME, TIME)
MFLD ITEMNUM,LTH=08,JUST=R,ATTR=YES
MFLD STCODE,LTH=03,JUST=L,ATTR=YES
MFLD STDTIN,LTH=08,JUST-L,ATTR=YES
MFLD STDTOUT,LTH=08,JUST=L,ATTR=YES
MFLD STDESC,LTH=22,JUST=L,ATTR=YES
MSGEND
END |
If you have any doubts or queries related to this chapter, get them clarified from our Mainframe experts on IBMMainframer Community!