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

Up to Top