31. imbed='xx' and other ways of calling external

Programs external to RXS may be called the following way:

·   Calling REXX and CLIST: call 'progrnme' 'parm' will call the REXX program progrnme using the parameter parm. Notice the use of quotes: RXS assumes every un-quoted name to be a variable. An alternative is to change address to tso, ispexec or attach, and then call the CLIST or REXX using the call format for these environments.

·   Changing address: To use commands in tso, ispexec, attach and any other environment: change address to the environment, and send one or more strings to output, the string(s) containing the commands. See Section 33h.

·   Calling RXS programs: call 'rxs' 'progrnme' 'parm' will call the RXS program progrnme using the parameter parm. Notice: this same way, a REXX program may call a RXS program. Notice the use of quotes: RXS assumes every un-quoted name to be a variable. The prerequisite for calling is that a RXSLIB library is allocated - see 'Installation of RXS'. If both calling and called RXS program uses SQL, it is better to use imbed:

·   Imbed is an alternative way of calling (or imbedding) a RXS program from RXS. The rest of this section will describe imbed:

)imbed in RXS works like copy / include in other languages. If execution of a RXS program reaches this line

)imbed imbed='mymbr'

execution continues in the member 'mymbr'. This member must by found in a dataset allocated to file RXSLIB in the TSO-session. As execution reaches the end of mymbr, then the line after the imbed-point in 'main' is executed next. All variables and queues in RXS before the imbed-point is also known inside mymbr. The connection also goes opposite: New values assigned to these values inside mymbr are at hand after return to 'main' RXS. The same applies to queues created inside mymbr.


Imbed uses one general order: imbed must be assigned the name of the member containing the RXS code to be imbedded.

Imbedded RXS coding must by syntactically correct considered on its own. For example, you cannot write an action block starting with )action in main RXS and terminated with      )endaction in imbedded RXS.

Imbed has two special features:

·   imbed=xvar do work: If a variable (here xvar) is assigned the name of a member, the variable can be used to govern imbed. That is: imbed is solved during execution, not in some pre-processing phase.

·   The coding inside the imbed member may itself contain )imbed. This chain of imbed may be of any depth.

Executing external code using imbed means that the imbedded coding will participate in the same unit-of-work as main RXS. Any error or a programmed exit will result in a rollback of any changes in files, MQSeries queues or DB2 tables.

If a RXS program uses SQL, and the program transfers control to another RXS program, the other program also using SQL, the transfer ought to be done by )imbed. Imbed supports any pattern of concurrent SQL cursors in the two RXS programs, and both programs will run in the same unit-of-work.

Using other call interfaces than imbed, the RXS program and the external coding will work in separate units-of-work. Meaning that the called coding may commit some change, while main RXS makes a rollback - or the opposite.


Example 31.1

)text out='degree'

  set current degree = 'ANY'


)text out='isola'

  set current packageset = 'DSNREXUR'


)action in='isola'

)&      func='sql'

  say "Using isolation level UR, that is: no DB2 locks checked"


)action in='degree'

)&      func='sql'

  say "Using current degree='any', that is: maximum parallelism "


The above coding could be written in a member called 'SQLTURBO' in a dataset allocated to file RXSLIB in the ISPF-session, opening up for this coding in another RXS program:

)imbed imbed='sqlturbo'

)text out='sqlcoding'

  select name, salary from our.employee


)action in='sqlcoding'

)&      func='sql'

  left(name,20) salary


Executing this RXS program will execute the specified select-call against DB2. No locks will be checked, and - if possible - the DB2 system will split the query in parallel executing parts and thereby speed up execution.  These two options are not programmed, but imbedded.


Variables to govern the imbedded coding may be stated anywhere in the RXS coding in the main program above the imbedding. To emphasize that some variables are used inside imbedded coding, you may also use the construct:

  Example 31.2

)imbed imbed='createit'

)&     object='yrsa'

)&     input='r2d2.c.txt(hugo)'

That is, using the notion for stating of general orders to state orders for an imbed.