CALL, CALL SYSTEM

Function

Issues an operating system command or calls a subroutine written in another language such as C or COBOL and passes the specified parameters.

Note:

CALL is available in all Production Reporting environments except Oracle's Hyperion® SQR® Production Reporting Studio. With Oracle's Hyperion® SQR® Production Reporting Studio, use CALL SYSTEM instead.

Syntax

CALL subroutine USING {src_txt_lit|_var|_col}|{src_num_lit|_var|_col} {dst_txt_var|_num_var}[param]

To issue operating system commands in an Production Reporting program, use the following syntax:

CALL SYSTEM USING command status [WAIT|NOWAIT]

Arguments

subroutine

Name of the subroutine.

src_txt_lit|_var|_col

Text column, variable, or literal to input into the called subroutine.

src_num_lit|_var|_col

Numeric column, variable (decimal, float, or integer), or literal to input into the called subroutine.

dst_txt_var|_num_var

Text or numeric variable (decimal, float, or integer) into which the called subroutine places the return result. (See Table 16, UCALL Subroutine Arguments .)

param

(Optional) Alphanumeric string of characters passed as a parameter to the subroutine.

SYSTEM

Defines that this CALL command issues an operating system command.

command

Operating system command to execute. The command can be a quoted string, string variable, or column.

status

Status returned by the operating system. The status must be a numeric variable. The value returned in status is system-dependent as shown in Table 15.

Table 15. Operating System Status Values for the CALL Command

System	Value Returned
UNIX	Zero (0) indicates success. Any other value is the system error code.
PC/Windows	A value less than 32 indicates an error.

WAIT|NOWAIT

(Windows) - WAIT suspends execution until CALL SYSTEM finishes processing. NOWAIT starts CALL SYSTEM while continuing its own processing.

For Windows, the default is NOWAIT. On UNIX operating systems the behavior is always WAIT.

Description

You can write your own subroutines to perform tasks that are awkward in Production Reporting. Subroutines can be written in any language.

Caution!

If ucall uses database calls, it may cause erroneous results.

Used in an Production Reporting program, CALL has the following format:

CALL your_sub USING source destination [param_literal]
CALL SYSTEM USING command status [WAIT|NOWAIT]

CALL SYSTEM is a subroutine provided with Production Reporting to allow the program to issue operating system commands. Its arguments, command, status, and WAIT|NOWAIT are described above.

The values of the source and destination variables and the parameter's literal value are passed to the subroutine. Upon return from the subroutine, a value is placed in the destination variable. If the arguments passed to the function are longer than the limit, they are truncated. (No warning message displays, but the call proceeds.)

Write the subroutine and call it in one of the supplied ucall routines. (Optionally, you could rewrite ucall in another language).

The source file UCALL.C contains sample subroutines written in C. :

Table 16. UCALL Subroutine Arguments

Argument	Description	How Passed
callname	Subroutine name.	By reference with a maximum of 31 characters, null terminated.
strsrc	Source string.	By reference with a maximum of 511 characters, null terminated.
strdes	Destination string.	By reference with a maximum of 511 characters, null terminated.
dblsrc	Source double floating point.	By reference.
dbldes	Destination double floating point.	By reference.
param	Subroutine parameter string. It must be a literal.	By reference with a maximum of 2047 characters, null terminated.

CALL arguments are handled as follows:

Arguments are copied into variables depending on argument type. Strings are placed in strsrc, and numerics are placed in dblsrc.
Return values are placed in strdes or dbldes depending on whether the destination argument for CALL is a string or numeric variable.
Destination arguments can be used to pass values to a subroutine.
To access a subroutine, add a reference to it in UCALL, passing along the needed arguments.
Relink Production Reporting to CALL after compiling a user-defined function that becomes another Production Reporting function.
Add subroutines to the link command file (UNIX: SQRMAKE, Windows: SQREXT.MAK) for new object files. (Alternatively, you could add the routine to the bottom of the UCALL source module included in the link).
Subroutines and calling Production Reporting programs are responsible for passing correct string or numeric variables and optional parameter strings to the subroutine. No checking is performed.

Examples

Sample subroutines included in the UCALL source file:

TODASH shows how strings can be manipulated.
SQROOT demonstrates how to access numerics.
SYSTEM invokes a secondary command processor.

The following code calls these subroutines:

call todash using $addr $newaddr '/.',! Convert these to dashes
call sqroot using #n #n2              ! Put square root of #n into #n2
call sqroot using &hnvr #j            ! Hnvr is numeric database column
call system using 'dir' #s            ! Get directory listing

The following example uses the SYSTEM argument to issue an operating system command. Some operating systems let you invoke a secondary command processor to enter one or more commands and then return to Production Reporting.

! Unix  (Type 'exit' to return to Production Reporting)
!
let $shell = getenv('SHELL')
if isblank($shell)
  let $shell = '/bin/sh'
end-if
call system using $shell #unix_status

!Windows 98/NT (Type 'exit' to return to Production Reporting)
!
let $comspec = getenv('COMSPEC')
let $cmd = comspec || '/c' ||$comspec || ' /k' 
call system using $cmd #win_status wait

The following example adds a user-defined subroutine to Production Reporting so that it can be invoked using CALL. For this example, the C function initcap, which uppercases the first letter of a string, is added. The function accepts two parameters. The first parameter is the string to which initcap is applied. The second is the resultant string.

Add the initcap prototype

static void initcap CC_ARGS((char *, char *));

Modify ucall in UCALL.C. Specifically, add an else if statement at the end of the if statement to check for initcap:

void ucall CC_ARGL((callname, strsrc, strdes, dblsrc, dbldes, params))
...	

       /* If other subroutines, add "else if..." statement for each */
       else if (strcmp(callname,"initcap") == 0)
           initcap(strsrc, strdes);
       else
           sq999("Unknown CALLed subroutine:  %s\n", callname);
       return;
       }

At the end of UCALL.C, add the initcap routine listed in the following example. The routine name must be lower case; however, in your Production Reporting program it can be referenced with either upper or lower case.

static void initcap CC_ARGL((strsrc, strdes))
CC_ARG(char *, strsrc)  /* Pointer to source string      */
CC_LARG(char *, strdes) /* Pointer to destination string */
  {
  int nIndex;
  int nToUpCase;
  char cChar;

  nToUpCase = 1;
  for (nIndex = 0; cChar = strsrc[nIndex]; nIndex++)
    {
    if (isalnum(cChar))
      {
      if (nToUpCase)
        strdes[nIndex] = islower(cChar) ? toupper(cChar) : cChar;
      else
        strdes[nIndex] = isupper(cChar) ? tolower(cChar) : cChar;
        nToUpCase = 0;
      }
    else
      {
        nToUpCase = 1;
        strdes[nIndex] = cChar;
      }
    }
  strdes[nIndex] = '\0';
  }

Note:

CC_ARG macros are defined in the UCALL.C source module. The macros allow you to define a fully prototyped function without having to worry if the C compiler supports the feature.

After these modifications, recompile UCALL.C and relink Production Reporting. See “Interoperability” in Volume 1 of the Hyperion SQR Production Reporting Developer's Guide for details.

The following is an example of a simple Production Reporting program using initcap:

begin-program
   input $name 'Enter the first name '
        ! Get the first name from the user

   lowercase $name
        ! Set the first name to all lower case

   call initcap using $name $capname 
        ! Now set the first character to upper case

   input $last 'Enter the last name '
        ! Get the last name from the user

   lowercase $last
        ! Set the last name to all lower case

   call initcap using $last $caplast  
        ! Now set the first character to upper case
.
.