BLDMPB — Build a message parameter block

Description

The BLDMPB macro builds the fixed portion of a message parameter block (MPB). If you are writing a new application or adding new messages to an existing application, you can place the message text in the install message files rather than in the application code. To translate message text that exists only in the install message files, you need to build an MPB.

An MPB consists of a fixed section and a variable length section. The fixed section contains control information, and the variable length section contains substitution data. The MPB does not contain any message text. Issue TRANMSG to retrieve the message text for this MPB. Issue BLDMPB once for each MPB that you want to construct. Use BLDMPB together with UPDTMPB.

See z/OS MVS Programming: Assembler Services Guide for more information on using the BLDMPB macro.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN or PASN=HASN¬=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt Status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Not applicable

Programming requirements

Before invoking BLDMPB, you must obtain storage for the MPB. You must include the mapping macro CNLMMPB. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for more information on CNLMMPB.

Restrictions

None.

Input register information

Before issuing the BLDMPB macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Reason code
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The BLDMPB macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede BLDMPB.

BLDMPB

␢	One or more blanks must follow BLDMPB.

MPBPTR=`mpb addr`	`mpb addr:` RX-type address or register (2) - (12).

,MPBLEN=`mpb length addr`	`mpb length addr`: RX-type address or register (2) - (12).

,MSGID=`msg id addr`	`msg id addr:` RX-type address or register (2) - (12).

,MSGIDLEN=`msg id length`	`msg id length addr`: RX-type address or register (2) - (12).
`addr`

,MSGFMTNM=`format num`	`format num addr`: RX-type address or register (2) - (12).
`addr`

,MSGLNNM=`line num addr`	`line num addr`: RX-type address or register (2) - (12).

Parameters

The parameters are explained as follows:

MPBPTR=mpb addr: Specifies the address or a register containing the address of the area in which BLDMPB is to build the MPB.
,MPBLEN=mpb length addr: Specifies the address or a register containing the address of the length of the area in which BLDMPB is to build the MPB. Determine the length by adding the length of the variable data to the length of the MPB header section. Variable data includes entries associated with each piece of substitution data.
,MSGID=msg id addr: Specifies the address or a register containing the address of the area that contains the message identifier.
,MSGIDLEN=msg id length addr: Specifies the address or a register containing the address of the length of the MSGID field. The message identifier can be up to 10 characters long. If you don't specify MSGIDLEN, BLDMPB will use, as a default, the length of the MSGID field in the DSECT mapping. You must specify MSGIDLEN if you use register notation for the MSGID keyword.
,MSGFMTNM=format num addr: Specifies the address or a register pointing to an area containing a 3-byte message format number. If you do not specify MSGFMTNM, the default is a blank.
,MSGLNNM=line num addr: Specifies the address or a register pointing to an area containing the 2-byte message line number. If you do not specify MSGLNNM, the default is a blank.

Return and reason codes

When BLDMPB completes, register 15 contains a return code, and register 0 contains a reason code:

Hexadecimal Return Code	Hexadecimal Reason Code	Meaning
00	00	Successful processing.
0C	33	The MPB is too small.
0C	34	The value for MSGIDLEN is zero or negative.

Example

Build and update an MPB for a message that contains as substitution data the third day of the week.

BLDMPBA  CSECT
BLDMPBA  AMODE  31
BLDMPBA RMODE  ANY
         STM    14,12,12(13)
         BALR   12,0
         USING  *,12
         ST     13,SAVE+4
         LA     15,SAVE
         ST     15,8(13)
         LR     13,15
***********************************************************************
*        OBTAIN WORKING STORAGE AREA FOR THE MPB                      *
***********************************************************************
         GETMAIN RU,LV=STORLEN,SP=SP230
         LR    R4,R1                    SAVE GETMAINED AREA ADDRESS
*
***********************************************************************
*        CREATE MPB HEADER SECTION                                    *
***********************************************************************
*
         BLDMPB MPBPTR=(R4),MPBLEN=MPBL,MSGID=MSGID,
               MSGIDLEN=MIDLEN
*
***********************************************************************
*        ADD SUBSTITUTION DATA TO MPB                                 *
***********************************************************************
*
         LR    R2,R4                  GET ADDRESS OF GETMAINED STORAGE
         A     R2,MPBL                ADD LENGTH OF MPB TO POINT TO   C
                                        VARIABLE AREA
         USING VARS,R2
*
         UPDTMPB MPBPTR=(R4),MPBLEN=MPBL,SUBOOFST=VARS,               C
               TOKEN=TOKN,TOKLEN=TOKL,TOKTYPE=TOKT,                   C
               SUBSDATA=SDATA,SUBSLEN=SDATAL
*
*

***********************************************************************
*        FREE STORAGE AREA                                            *
***********************************************************************
*
         FREEMAIN RU,LV=STORLEN,SP=SP230,A=(4)
*
         L     13,SAVE+4
         LM    14,12,12(13)
         BR    14
         DROP
***********************************************************************
MPBL     DC    A(MPBLEN)           ADDRESS OF MPB LENGTH
MSGID    DC    CL10'MSGID2'        MSG ID OF MESSAGE REPRESENTED BY MPB
MIDLEN   DC    A(MIDL)             ADDRESS OF MSG ID LENGTH
TOKN     DC    CL3'DAY'            TOKEN NAME
TOKL     DC    F'3'                LENGTH OF TOKEN NAME
TOKT     DC    CL1'3'              TOKEN TYPE (DAY)
SDATA    DC    CL1'3'              SUBSTITUTION DATA (3RD DAY OF WEEK)
SDATAL   DC    A(SDL)              ADDRESS OF SUBSTITUTION DATA LENGTH
SAVE     DC    18F'0'              SAVE AREA
SP230    EQU   230                 SUBPOOL SPECIFICATION FOR GETMAIN
STORLEN  EQU   256                 LENGTH OF GETMAINED STORAGE
SDL      EQU   6                   SUBSTITUTION DATA LENGTH
MIDL     EQU   6                   MSG ID LENGTH
MPBLEN   EQU   (MPBVDAT-MPB)+(MPBMID-MPBMSG)+(MPBSUB-MPBSB)+MIDL+SDL C
                                   TOTAL MPB LENGTH
R1       EQU   1                   REGISTER 1
R2       EQU   2                   REGISTER 2
R4       EQU   4                   REGISTER 3
***********************************************************************
         DSECT
         CNLMMPB
VARS     DSECT
VARSAREA DS    CL24
VARSLEN  EQU   *-VARS
         END BLDMPBA