When SBX calls were first implemented, a special MIAMEX function, MX_XCBDATAX, was added to facilitate passing parameters between the caller and the SBX. Since A-Shell 5.0, these have been deprecated and superseded by X???ARG* statements, which, in addition to handling SBX parameters, also handle function and procedure parameters. Although the MX_XCBDATAX statements continue to operate, we recommend converting them whenever possible.
The following examples may clarify the equivalencies between the new statements and the old MX_XCBDATAX calls:
XGETARGS P1,P2,P3,P4
is equivalent to:
xcall MIAMEX, MX_XCBDATAX, XCBADR, XCBGET,1,P1
xcall MIAMEX, MX_XCBDATAX, XCBADR, XCBGET,2,P2
xcall MIAMEX, MX_XCBDATAX, XCBADR, XCBGET,3,P3
xcall MIAMEX, MX_XCBDATAX, XCBADR, XCBGET,4,P4
and is also equivalent to:
XGETARG 1,P1
XGETARG 2,P2
XGETARG 3,P3
XGETARG 4,P4
For returning arguments,
xcall MIAMEX, MX_XCBDATAX, XCBADR, XCBPUT,1,A+B/C
is equivalent to:
XPUTARG 1,A+B/C
The main advantage of the new statements is just efficiency, both for the programmer and for the computer. This is especially true if you use XGETARGS to retrieve all arguments in one statement.
Note that these new statements do not require XCBADR or any of the other variables set up by ASHINC:XCALL.BSI. However, you may still want to continue including xcall.bsi at the start of your SBX modules since it does set the variable XCBCNT to the number of parameters passed, and the XCBSTRUCT() array to the types and sizes, and this information can be useful in determining how to interpret the passed parameters. XGETARGS and XGETARG do not give you any obvious indication when fewer parameters were passed to the subroutine than the subroutine is expecting, so a well-written subroutine should, at a minimum, check XCBCNT to see how many parameters were passed.
All of the X???ARG* statements require the compiler /X:2 switch.
