Writing a Subroutine

A subroutine name can be up to eight characters long unless the language you are using to write the subroutine requires a shorter name. A name must start with a letter and can consist of a combination of letters and/or numbers. Special symbols are not permitted.

When you create arguments for a subroutine, you must consider the following issues:

• Maximum number of arguments. A subroutine may contain up to 200 arguments. You can bypass this restriction by creating a subroutine that accepts multiple calls, as described in Including More Than 200 Arguments in a Subroutine Call.
• Argument types. You can use the same types of arguments in a subroutine as in a function. For details on these argument types, see Argument Types.
• Input arguments. Input arguments are passed to a subroutine using standard conventions. Register one points to the list of arguments.

  You should not assume that input parameters are stored in contiguous memory.

• Output arguments. A subroutine returns only one output argument. This argument must be the last in the subroutine. You can choose any format for the output argument except in Dialogue Manager which requires the argument to have the format of the output field.
• Internal processing. A subroutine's arguments are processed as follows:
  • An alphanumeric argument is not changed.
  • A numeric argument is converted to floating-point double-precision format except in an operating system RUN command or when storing the output in a variable.
• Dialogue Manager requirements. If you are writing a subroutine specifically for Dialogue Manager, the subroutine may need to perform a conversion. For details on using a subroutine with Dialogue Manager, see Calling a Function From a Dialogue Manager Command.
• COBOL requirements. All parameters must be defined at the same level in the COBOL FD. Alternatively, you can concatenate all of the parameters into one string, and break them apart within the subroutine.

The lengths of the calling arguments as defined in WebFOCUS must match the lengths of the corresponding arguments defined in the subroutine.

Any deviation from these rules may result in problems in using the subroutine. Information Builders recommends that you modify the subroutine to conform to the stated rules and then link it above the line. In order to load subroutines above the line, the following are the required link-edit options for compiling and storing the subroutine:

• AMODE 31 (Addressing Mode - 31-bit addressing)
• RMODE ANY (System can load this routine anywhere)

When writing a subroutine, you must consider the following language issues:

Language and memory. If you write a subroutine in a language that brings libraries into memory (for example, FORTRAN and COBOL), the libraries reduce the amount of memory available to the subroutine.

FORTRAN. TSO supports FORTRAN input/output operations.

COBOL. When writing a subroutine in COBOL:

• The subroutine must use the GOBACK command to return to the calling program. STOPRUN is not supported.
• Numeric arguments received from a request must be declared as COMP-2 (double precision floating point).
• The format described in the DEFINE or COMPUTE command determines the format of the output argument:

  WebFOCUS Format	Picture
  An	Xn
  I	S9(9) COMP
  P	S9(n)[V9(m)] where: (1+n+m)/2 = 8 for small packed numbers. (1+n+m)/2 = 16 for large packed numbers.
  D	COMP-2
  F	COMP-1

PL/I. When writing a subroutine in PL/I:

• The RETURNS attribute cannot be used.
• The following attribute must be in the procedure (PROC) statement:

  OPTIONS (COBOL)

• Alphanumeric arguments received from a request must be declared as

  CHARACTER (n)

  where:

  n

  Is the field length as defined by the request. Do not use the VARYING attribute.

• Numeric arguments received from a request must be declared as

  DECIMAL FLOAT (16)

  or

  BINARY FLOAT (53)

• The format described in the DEFINE or COMPUTE command determines the format of the output argument:

  WebFOCUS Format	PL/I Declaration for Output
  An	CHARACTER (n)
  I	BINARY FIXED (31)
  F	DECIMAL FLOAT (6) or BINARY FLOAT (21)
  D	DECIMAL FLOAT (16) or BINARY FLOAT (53)
  P	DECIMAL FIXED (15) (for small packed numbers, 8 bytes) DECIMAL FIXED (31) (for large packed numbers, 16 bytes)

• Variables that are not arguments with the STATIC attribute must be declared. This avoids dynamically allocating these variables every time the subroutine is executed.

C language. When writing a subroutine in C:

• Do not return a value with the return statement.
• Declare double-precision fields as Double.
• The format defined in the DEFINE or COMPUTE command determines the format of the output argument:

  WebFOCUS Format	C Declaration for Output
  An	char *xxx n Alphanumeric fields are not terminated with a null byte and cannot be processed by many of the string manipulation subroutines in the run-time library.
  I	long *xxx
  F	float *xxx
  D	double *xxx
  P	No equivalent in C.

Consider the following when planning your programming requirements:

• Write the subroutine to include an argument that specifies the output field.
• If the subroutine initializes a variable, it must initialize it each time it is executed (serial reusability).
• Since a single request may execute a subroutine numerous times, code the subroutine as efficiently as possible.
• If you create your subroutine in a text file or text library, the subroutine must be 31-bit addressable.
• The last argument, which is normally used for returning the result of the subroutine, can also be used to provide input from the subroutine.

You can add flexibility to your subroutine by using a programming technique. A programming technique can be one of the following:

• Executing a subroutine at an entry point. An entry point enables you to use one algorithm to produce different results. For details, see Executing a Subroutine at an Entry Point.
• Creating a subroutine with multiple subroutine calls. Multiple calls enable the subroutine to process more than 200 arguments. For details, see Including More Than 200 Arguments in a Subroutine Call.