Calling a Subroutine From a Procedure

A ReportCaster API subroutine passes a required set of arguments in a specified order and supplies a return code to the calling procedure. You can change the Dialogue Manager variable names (amper variables), or replace them with coded values. The following variable names used are samples.

Note: This is the general syntax for all subroutines. For more information about the syntax for each subroutine, see the specific sections that describe the DSTBULK, DSTMEM, and DSTRUN subroutines.

-SET &var_name=API_subrtn_name(srv_userid,srv_userid_length,
-  'srv_userpass',srv_userpass_length,
-  'hostname_port',hostname_port_length,
-  'input7',
-  'input8',
.
.
.
-  'httpuser/pswd',httpuser/pswd_length, 
[-  'tcpiplevel',]
-  'I4');

where:

&var_name

Is the variable that will contain the return code.

API_subrtn_name

Is the API subroutine, which can be DSTBULK, DSTMEM, or DSTRUN.

srv_userid

Is a valid Execution ID. It must match the user ID stored in the WebFOCUS repository with the job information.

srv_userid_length

Is the length of the Execution ID.

srv_userpass

Is a valid password for the Execution ID. It must match the password of the user ID stored in the WebFOCUS repository with the job information.

srv_userpass_length

Is the length of the password for the Execution ID.

hostname_port

Is the host name (or IP address) and port number of the web server on which the WebFOCUS Client is installed. The maximum character length is 30.

If the port number is 80 (the default), you may omit the colon and port number. For example,

'hostname',

If the port number is not 80, use a colon as a delimiter and then specify the port number. The maximum character length is 10. For example,

'hostname:81',

hostname_port_length

Is the length of the host name and port number. This is only the length of the host name if the port number is omitted.

input7,input8, ...,

Are the input arguments (the values required by the subroutine). These arguments are different for each subroutine.

httpuser/pswd

Is a valid user ID and password for the web server, separated by the forward slash character ( / ). A user ID and password are required if the web server is running with security on.

httpuser/pswd_length

Is the length of the web server user ID and password, including the forward slash character ( / ).

tcpiplevel

Required only if the WebFOCUS Reporting Server runs on OS/390. This argument is the method the ReportCaster API uses for securing sockets from TCP/IP, based on a specific SAS/C library. Valid values are:

• 1, which resolves special connectivity problems.
• 0, which indicates that there are no special connectivity problems.

'I4'

Is the format of the return code. For more information, see ReportCaster API Subroutine Messages.

When you code a ReportCaster API subroutine:

• You must code the arguments passed to the API subroutine in the exact order as shown in Call an API Subroutine Using -SET. The arguments are positional.

  If you do not supply all arguments, the subroutine terminates, and a TSCOM3 message may be generated.

  The only exception is the argument tcpiplevel, which is required only if the WebFOCUS Reporting Server runs on OS/390. If your server does not run on OS/390, you must omit this argument.

• If you do not supply a value for an alphanumeric argument that is optional, you must code the following to hold the position for the argument and to indicate a length of zero. There is one space between the single quotation marks (' '):

  ' ',0,

• You must code a comma to separate arguments.
• You must code alphanumeric values in single quotation marks. For example, if the name of the WebFOCUS Reporting Server is IBIWNT and the port number is 1234, you must code the value as 'IBIWNT:1234'.
• You must code a continuation line with a hyphen (-) followed by one or more spaces.

The ReportCaster API provides a pair of identification arguments as input to certain subroutines.

• jobdesc. This is a user-supplied description that identifies a report request (job) scheduled for execution and distribution. The value must be unique for a given Execution ID. The description can be up to 90 alphanumeric characters with embedded blanks and special characters.
• scheduleid. This is a unique, API-generated, 12-digit ID that identifies a scheduled job in the WebFOCUS repository. It is automatically created when a user schedules a job.

You can identify a job to the ReportCaster API with either the jobdesc or the scheduleid argument.

Note: The ReportCaster Administrator can determine a schedule ID for a job by running the report from the ReportCaster Console. Both administrators and users can determine a schedule ID by using the Log File icon on gray toolbar of the ReportCaster Interface.

You can call a procedure from an HTML form. The following sample HTML code calls a procedure, which in turn calls a ReportCaster API subroutine. For more details on coding syntax, see the Developing Reporting Applications manual, and the HTML files residing on /ibi_html/broker/.

<FORM ACTION="/cgi-bin/ibi_cgi/ibiweb.exe" METHOD="get">
<INPUT NAME="IBIF_ex" VALUE="procedure_name" TYPE="hidden">

where:

procedure_name

Is the name of the procedure to run. It contains the call to the ReportCaster API subroutine. A procedure must reside in a path defined to the WebFOCUS Reporting Server. On Windows and UNIX, it must be located in EDAPATH. On OS/390, it must be in a partitioned data set (PDS) allocated to ddname EDARPC. Do not specify the file name extension in the VALUE= field.