BLDCALL Build Call Command

BLDCALL BUILD CALL FOR SBMJOB COMMAND TAABLDA
Note: This function is primarily replaced by the CMD parameter on SBMJOB. It provides the same advantages. BLDCALL is useful if you have a long parameter list on a call that you need to either submit to batch or execute using QCMDEXC. See the TAASYSDC CL program for an example. If you only need to submit to batch, you should use the SBMJOB CMD parameter. Two commands are provided (BLDCALL and BLDCALL2). BLDCALL2 is the same function, but the RQSDTA parameter is increased to 3000 bytes (the new limit on SBMJOB). The BLDCALL command is specifically designed to assist you in building a CALL command with parameters that is to be submitted to batch. The following is a typical use of the command: DCL &RQSDTA *CHAR LEN(256) DCL &X *CHAR LEN(10) DCL &Y *CHAR LEN(5) . . BLDCALL RQSDTA(&RQSDTA) PGM(PGMA) PARM(&X &Y 1) SBMJOB RQSDTA(&RQSDTA) If &X = ABCDEF and &Y = MNOP, the command submitted to batch would be: CALL PGMA PARM('ABCDEF' 'MNOP' '1') The BLDCALL command has the following advantages: ** BLDCALL eliminates the coding complexities of using the CHGVAR command with concatenation and multiple apostrophes to assemble the CALL command. To perform the same function with a CHGVAR command would be: CHGVAR &RQSDTA ('CALL PGMA PARM(' *CAT '''' *CAT &X + *CAT '''' *BCAT '''' *CAT &Y *CAT '''' + *BCAT '''' *CAT '1' *CAT '''' *CAT ')') ** BLDCALL eliminates the problem that can occur when one of the parameters is blank and has not been surrounded with apostrophes. In this case, the command analyzer will not recognize that a parameter exists and this can often result in considerable debugging effort. For example, assume the CHGVAR command had been coded as: CHGVAR &RQSDTA ('CALL PGMA PARM(' *CAT &X *BCAT &Y + *CAT '1' *CAT ')') and &X contains blanks. The command passed into batch would appear as: CALL PGMA PARM(MNOP 1) and MNOP (the value intended for the second parameter) would be placed in the first parameter and a 1 placed in the second parameter. This problem is avoided by the fact that the parameters are always surrounded by apostrophes by the BLDCALL command. ** BLDCALL eliminates the problem of a character variable with an embedded blank being treated as two parameters when the command is analyzed in batch. For example if &X had contained (MILK MAN) and had not been surrounded with apostrophes, the resulting command passed to batch would contain four parameters as: CALL PGMA PARM(MILK MAN MNOP 1) This can also result in considerable debugging effort and is avoided by the fact that the BLDCALL command always places apostrophes around the variables. ** BLDCALL eliminates the problem of numeric data intended to be treated as character from being treated as a decimal value. There are two conditions where this can cause confusion: -- The constant '1' which needs to be passed must be surrounded with apostrophes to be treated as character. If the following is passed to batch: CALL PGMA PARM(ABCDEF MNOP 1) the third parameter will be treated as a numeric value and will be packed by the system. -- This can also occur when a variable contains numeric data. For example, if &X contains 123 and had not been surrounded with apostrophes, the following would have been passed to batch. CALL PGMA PARM(123 MNOP 1) In this case, the command analyzer would treat the first parameter as numeric and pass it to the program as a packed decimal value. ** BLDCALL eliminates the need to have to define *DEC type variables in batch as having a length of (15 5). When a command string is analyzed by the command analyzer, any numeric values are treated as if they had been defined with a (15 5) definition. The failure to properly code for this definition can result in considerable debugging effort. Since all parameters are forced to be passed as character, your programs do not have to be aware of this command analyzer definition. Your program need only make the simple conversion from character to decimal. Restrictions ------------ ** Because the BLDCALL command requires a return variable, the command can only be executed within a CL program. ** Only character variables may be used. If a *DEC type must be passed, it must first be converted to character. If a *DEC type is specified, the CRTCLPGM command will fail with an appropriate diagnostic. ** Character variables cannot exceed 32 bytes in length. If a longer length is specified, the program will compile correctly, but will abort during execution regardless of the number of characters in the variable. If a long character variable must be passed, you may place it in multiple 32 byte variables. ** As with SBMJOB, the RQSDTA parameter is limited to 256 bytes. If you attempt to assemble more than 256 bytes, an escape message will be sent during execution. The BLDCALL2 command is the same function, but the size of the RQSDTA is increased to 3000 bytes. See BLDCALL2. BLDCALL Command parameters *CMD -------------------------- RQSDTA The return variable that will be used in the SBMJOB command. It must be defined as *CHAR LEN(256). PGM The qualified program name that will be placed in the the SBMJOB command. The default for the library is *LIBL. PARM A list of up to 50 entries that define the parameters to be used on SBMJOB. Only character variables may be used. The length of each cannot exceed 32 characters. A numeric value (e.g. 132) may be entered, but it will be passed as a character value. All entries will have apostrophes surrounding them on the SBMJOB command. BLDCALL2 Command parameters *CMD --------------------------- RQSDTA The return variable that will be used in the SBMJOB command. It must be defined as *CHAR LEN(3000). PGM The qualified program name that will be placed in the the SBMJOB command. The default for the library is *LIBL. PARM A list of up to 50 entries that define the parameters to be used on SBMJOB. Only character variables may be used. The length of each cannot exceed 32 characters. A numeric value (e.g. 132) may be entered, but it will be passed as a character value. All entries will have apostrophes surrounding them on the SBMJOB command. Example ------- When you want to pass a *DEC type variable, you must first convert it to a character variable. When changing to a character variable, you must consider the length of the character field. It must be large enough to contain a decimal point (if it exists) and a minus sign (if the field is negative). CL Code DCL &COUNT *DEC LEN(3 0) VALUE(50) DCL &AMT1 *DEC LEN(5 2) VALUE(10.32) DCL &AMT2 *DEC LEN(5 2) VALUE(-110.50) DCL &COUNTA *CHAR LEN(3) DCL &AMT1A *CHAR LEN(6) DCL &AMT2A *CHAR LEN(7) DCL &RQSDTA *CHAR LEN(256) . . CHGVAR &COUNTA &COUNT CHGVAR &AMT1A &AMT1 CHGVAR &AMT2A &AMT2 BLDCALL RQSDTA(&RQSDTA) PGM(PGMB) PARM(&COUNTA &AMT1A + &AMT2A) SBMJOB RQSDTA(&RQSDTA) The resulting command placed into batch would be: CALL PGMB PARM('050' '010.32' '-110.50') Note that the &COUNTA field is the same length as &COUNT since it has 0 decimals and is assumed to be only positive. The &AMT1A field is one position longer than the &AMT1 field to allow for the decimal point and is assumed to be always positive. The &AMT2A field is two positions longer than the &AMT2 field to account for the decimal position and the minus sign. The batch program (assume it is CL) will allow you to place the character values back into the proper numeric variables. The CHGVAR command will perform decimal alignment. You should avoid passing a value containing a decimal point directly to RPG. It is easier to let CL convert the value (place it in a packed field with an implied decimal point) and then pass the converted value to RPG. If PGMB is a CL program, it would be coded as follows: PGM PARM(&COUNTA &AMT1A &AMT2A) DCL &COUNT *DEC LEN(3 0) DCL &AMT1 *DEC LEN(5 2) DCL &AMT2 *DEC LEN(5 2) DCL &COUNTA *CHAR LEN(3) DCL &AMT1A *CHAR LEN(6) DCL &AMT2A *CHAR LEN(7) DCL &RQSDTA *CHAR LEN(256) . . CHGVAR &COUNT &COUNTA CHGVAR &AMT1 &AMT1A CHGVAR &AMT2 &AMT2A If you want to pass a long character variable (more than 32 bytes) you can break up the variable. For example, assume you want to pass a 50 byte variable you could do it as: DCL &BIG *CHAR LEN(50) VALUE('....50 bytes worth...') DCL &VAR1 *CHAR LEN(25) DCL &VAR2 *CHAR LEN(25) DCL &RQSDTA *CHAR LEN(256) . . CHGVAR &VAR1 %SST(&BIG 1 25) CHGVAR &VAR2 %SST(&BIG 26 25) BLDCALL RQSDTA(&RQSDTA) PGM(PGMB) PARM(&VAR1 &VAR2) SBMJOB RQSDTA(&RQSDTA) Prerequisites ------------- The following TAA Tools must be on your system: SNDESCMSG Send escape message Implementation -------------- None, the tool is ready to use. Objects used by the tool ------------------------ Object Type Attribute Src member Src file ------ ----- --------- ---------- ----------- BLDCALL *CMD TAABLDA QATTCMD BLDCALL2 *CMD TAABLDA2 QATTCMD TAABLDAC *PGM CLP TAABLDAC QATTCL TAABLDAC2 *PGM CLP TAABLDAC2 QATTCL Structure --------- BLDCALL Cmd TAABLDAC CLP BLDCALL2 Cmd TAABLDAC2 CLP


BLDCALL BUILD CALL FOR SBMJOB COMMAND TAABLDA
Note: This function is primarily replaced by the CMD parameter on SBMJOB. It provides the same advantages. BLDCALL is useful if you have a long parameter list on a call that you need to either submit to batch or execute using QCMDEXC. See the TAASYSDC CL program for an example. If you only need to submit to batch, you should use the SBMJOB CMD parameter. Two commands are provided (BLDCALL and BLDCALL2). BLDCALL2 is the same function, but the RQSDTA parameter is increased to 3000 bytes (the new limit on SBMJOB). The BLDCALL command is specifically designed to assist you in building a CALL command with parameters that is to be submitted to batch. The following is a typical use of the command: DCL &RQSDTA CHAR LEN(256) DCL &X CHAR LEN(10) DCL &Y CHAR LEN(5) . . BLDCALL RQSDTA(&RQSDTA) PGM(PGMA) PARM(&X &Y 1) SBMJOB RQSDTA(&RQSDTA) If &X = ABCDEF and &Y = MNOP, the command submitted to batch would be: CALL PGMA PARM('ABCDEF' 'MNOP' '1') The BLDCALL command has the following advantages: * BLDCALL eliminates the coding complexities of using the CHGVAR command with concatenation and multiple apostrophes to assemble the CALL command. To perform the same function with a CHGVAR command would be: CHGVAR &RQSDTA ('CALL PGMA PARM(' CAT '''' CAT &X + CAT '''' BCAT '''' CAT &Y CAT '''' + BCAT '''' CAT '1' CAT '''' CAT ')') ** BLDCALL eliminates the problem that can occur when one of the parameters is blank and has not been surrounded with apostrophes. In this case, the command analyzer will not recognize that a parameter exists and this can often result in considerable debugging effort. For example, assume the CHGVAR command had been coded as: CHGVAR &RQSDTA ('CALL PGMA PARM(' CAT &X BCAT &Y + CAT '1' CAT ')') and &X contains blanks. The command passed into batch would appear as: CALL PGMA PARM(MNOP 1) and MNOP (the value intended for the second parameter) would be placed in the first parameter and a 1 placed in the second parameter. This problem is avoided by the fact that the parameters are always surrounded by apostrophes by the BLDCALL command. BLDCALL eliminates the problem of a character variable with an embedded blank being treated as two parameters when the command is analyzed in batch. For example if &X had contained (MILK MAN) and had not been surrounded with apostrophes, the resulting command passed to batch would contain four parameters as: CALL PGMA PARM(MILK MAN MNOP 1) This can also result in considerable debugging effort and is avoided by the fact that the BLDCALL command always places apostrophes around the variables. BLDCALL eliminates the problem of numeric data intended to be treated as character from being treated as a decimal value. There are two conditions where this can cause confusion: -- The constant '1' which needs to be passed must be surrounded with apostrophes to be treated as character. If the following is passed to batch: CALL PGMA PARM(ABCDEF MNOP 1) the third parameter will be treated as a numeric value and will be packed by the system. -- This can also occur when a variable contains numeric data. For example, if &X contains 123 and had not been surrounded with apostrophes, the following would have been passed to batch. CALL PGMA PARM(123 MNOP 1) In this case, the command analyzer would treat the first parameter as numeric and pass it to the program as a packed decimal value. ** BLDCALL eliminates the need to have to define DEC type variables in batch as having a length of (15 5). When a command string is analyzed by the command analyzer, any numeric values are treated as if they had been defined with a (15 5) definition. The failure to properly code for this definition can result in considerable debugging effort. Since all parameters are forced to be passed as character, your programs do not have to be aware of this command analyzer definition. Your program need only make the simple conversion from character to decimal. Restrictions ------------ * Because the BLDCALL command requires a return variable, the command can only be executed within a CL program. ** Only character variables may be used. If a DEC type must be passed, it must first be converted to character. If a DEC type is specified, the CRTCLPGM command will fail with an appropriate diagnostic. Character variables cannot exceed 32 bytes in length. If a longer length is specified, the program will compile correctly, but will abort during execution regardless of the number of characters in the variable. If a long character variable must be passed, you may place it in multiple 32 byte variables. As with SBMJOB, the RQSDTA parameter is limited to 256 bytes. If you attempt to assemble more than 256 bytes, an escape message will be sent during execution. The BLDCALL2 command is the same function, but the size of the RQSDTA is increased to 3000 bytes. See BLDCALL2. BLDCALL Command parameters CMD -------------------------- RQSDTA The return variable that will be used in the SBMJOB command. It must be defined as CHAR LEN(256). PGM The qualified program name that will be placed in the the SBMJOB command. The default for the library is LIBL. PARM A list of up to 50 entries that define the parameters to be used on SBMJOB. Only character variables may be used. The length of each cannot exceed 32 characters. A numeric value (e.g. 132) may be entered, but it will be passed as a character value. All entries will have apostrophes surrounding them on the SBMJOB command. BLDCALL2 Command parameters CMD --------------------------- RQSDTA The return variable that will be used in the SBMJOB command. It must be defined as CHAR LEN(3000). PGM The qualified program name that will be placed in the the SBMJOB command. The default for the library is LIBL. PARM A list of up to 50 entries that define the parameters to be used on SBMJOB. Only character variables may be used. The length of each cannot exceed 32 characters. A numeric value (e.g. 132) may be entered, but it will be passed as a character value. All entries will have apostrophes surrounding them on the SBMJOB command. Example ------- When you want to pass a DEC type variable, you must first convert it to a character variable. When changing to a character variable, you must consider the length of the character field. It must be large enough to contain a decimal point (if it exists) and a minus sign (if the field is negative). CL Code DCL &COUNT DEC LEN(3 0) VALUE(50) DCL &AMT1 DEC LEN(5 2) VALUE(10.32) DCL &AMT2 DEC LEN(5 2) VALUE(-110.50) DCL &COUNTA CHAR LEN(3) DCL &AMT1A CHAR LEN(6) DCL &AMT2A CHAR LEN(7) DCL &RQSDTA CHAR LEN(256) . . CHGVAR &COUNTA &COUNT CHGVAR &AMT1A &AMT1 CHGVAR &AMT2A &AMT2 BLDCALL RQSDTA(&RQSDTA) PGM(PGMB) PARM(&COUNTA &AMT1A + &AMT2A) SBMJOB RQSDTA(&RQSDTA) The resulting command placed into batch would be: CALL PGMB PARM('050' '010.32' '-110.50') Note that the &COUNTA field is the same length as &COUNT since it has 0 decimals and is assumed to be only positive. The &AMT1A field is one position longer than the &AMT1 field to allow for the decimal point and is assumed to be always positive. The &AMT2A field is two positions longer than the &AMT2 field to account for the decimal position and the minus sign. The batch program (assume it is CL) will allow you to place the character values back into the proper numeric variables. The CHGVAR command will perform decimal alignment. You should avoid passing a value containing a decimal point directly to RPG. It is easier to let CL convert the value (place it in a packed field with an implied decimal point) and then pass the converted value to RPG. If PGMB is a CL program, it would be coded as follows: PGM PARM(&COUNTA &AMT1A &AMT2A) DCL &COUNT DEC LEN(3 0) DCL &AMT1 DEC LEN(5 2) DCL &AMT2 DEC LEN(5 2) DCL &COUNTA CHAR LEN(3) DCL &AMT1A CHAR LEN(6) DCL &AMT2A CHAR LEN(7) DCL &RQSDTA CHAR LEN(256) . . CHGVAR &COUNT &COUNTA CHGVAR &AMT1 &AMT1A CHGVAR &AMT2 &AMT2A If you want to pass a long character variable (more than 32 bytes) you can break up the variable. For example, assume you want to pass a 50 byte variable you could do it as: DCL &BIG CHAR LEN(50) VALUE('....50 bytes worth...') DCL &VAR1 CHAR LEN(25) DCL &VAR2 CHAR LEN(25) DCL &RQSDTA CHAR LEN(256) . . CHGVAR &VAR1 %SST(&BIG 1 25) CHGVAR &VAR2 %SST(&BIG 26 25) BLDCALL RQSDTA(&RQSDTA) PGM(PGMB) PARM(&VAR1 &VAR2) SBMJOB RQSDTA(&RQSDTA) Prerequisites ------------- The following TAA Tools must be on your system: SNDESCMSG Send escape message Implementation -------------- None, the tool is ready to use. Objects used by the tool ------------------------ Object Type Attribute Src member Src file ------ ----- --------- ---------- ----------- BLDCALL CMD TAABLDA QATTCMD BLDCALL2 CMD TAABLDA2 QATTCMD TAABLDAC PGM CLP TAABLDAC QATTCL TAABLDAC2 *PGM CLP TAABLDAC2 QATTCL Structure --------- BLDCALL Cmd TAABLDAC CLP BLDCALL2 Cmd TAABLDAC2 CLP

Added to TAA Productivity Tools April 1, 1995

Home Page

Last modified on January 12, 2010