Chapter Contents
Previous
Next
Run-Time Argument Processing

Run-Time Options

This section covers the various run-time options you can specify for program execution. These options can be specified in the following two ways:

Although both forms of the option control the library, options specified on the command line are usually referred to as command-line options, and options coded in the program source are referred to as program-specified options. No matter which method you use to specify options, there is a limit of 1000 characters for the string that contains run-time options and user parameters. Note that it is possible to circumvent this limit using argument redirection.

Command-line options have the form =option . Options specified in this way are only in effect for the current execution of the program.

Program-specified options are specified by an external variable and are in effect for every execution of the program (unless overridden by an option from the command line).

For example, under CMS the =minimal command-line option is specified on the program's command line as follows: 

cpgm arg1 =minimal

Specifying the option in this form indicates that you want a minimal form of program linkage for only this execution of your program. If you wanted always to have the minimal option in effect, however, you would code it in the program as follows: 

char _linkage = _MINIMAL;

Note that program option specification is not portable.

The run-time options can be grouped as follows:

Each group of options is discussed in detail in the following sections.

General Run-Time Options

These options control basic actions performed by the SAS/C Library. Most of these options can be specified either directly on the command line or in the program source. Command-line options begin with the equal sign (=). Most command-line options can be negated using the prefix no . For example, the negation of the =warning option can be specified as =nowarning .

Command-line options can be abbreviated by omitting final characters if no confusion with another option is possible. The abbreviation for each option is listed later in this section with the option description. Options can be specified in either upper- or lowercase.

Each option has a default specification. A program also can specify its own default by initializing an external variable for the option. A command-line specification always overrides any program-specified default.

General Run-Time Options lists sets of general options available for controlling run-time processing. Each option is discussed in detail following the table. The command-line specification is covered in the first section, followed by the program-specification form. General run-time options specified in the program source must be in uppercase.

General Run-Time Options
Specified on the Command Line

Specified in the Program Source

option negation int_options int_negopts
=abdump =noabdump -ABDUMP _NOABDUMP
=btrace =nobtrace _BTRACE _NOBTRACE
=cnftrace =nocnfrace _CNFTRACE _NOCNFTRACE
=debug =nodebug _DEBUG _NODEBUG
=fillmem =nofillmem _FILLMEM _NOFILLMEM
=hcsig =nohcsig _HCSIG _NOHCSIG
=htsig =nohtsig _HTSIG _NOHTSIG
=multitask =nomultitask _MULTITASK _NOMULTITASK
=quit =noquit _QUIT _NOQUIT
=storage =nostorage _STORAGE _NOSTORAGE
=usage =nousage _USAGE _NOUSAGE
=version =noversion _VERSION _NOVERSION
=warning =nowarning _WARNING _NOWARNING
=xtrace
 =noxtrace
 _XTRACE
 _NOXTRACE
=zeromem =nozeromem _ZEROMEM _NOZEROMEM

The meaning of each general run-time option is discussed below. The options are shown in command-line form; the program specification is discussed following this section.

=abdump
=a
produces a dump when an ABEND occurs, including an ABEND that is recovered by a SIGABRT or SIGABND signal handler. Under OS/390, =abdump is only meaningful in the case that an ABEND is recovered, since a dump is always produced (if an appropriate DD card is allocated) if the ABEND is not recovered.

Obtaining an ABEND dump under the USS shell can be tedious, because the mechanism that supports this (defining a SYSMDUMP data set before invoking the TSO OMVS command to bring up the shell) applies to all descendants of the shell. The =abdump run-time option overcomes this difficulty. If =abdump is specified for a program with exec -linkage, the library allocates the OS/390 data set userid.SASC.DUMP to the DDname SYSUDUMP during program startup. If the file cannot be allocated (perhaps because it is in use by another process) a diagnostic is generated and execution proceeds normally. You can use a dump file other than userid.SASC.DUMP with the =abdump option if you export the environment variable ddn_SYSUDUMP with the name of an alternate dump data set.

=btrace
=b
causes a traceback to be included with library warning messages. The default is =nobtrace .

Note:    The =btrace name is used to distinguish this option from the =trace option, which invokes the debugger.  [cautionend]

=cnftrace
displays TCP/IP configuration information. The display has the following format: 
LSCX077 TCP/IP Config Trace: [text]

=debug
=d
requests the use of the SAS/C Debugger, as described in the SAS/C Debugger User's Guide and Reference.

If you are executing an all-resident module using the =debug or =trace options, you must also define the macro name ALLOW_TRANSIENT in the module that includes <resident.h> .

Note:    When you specify this option, =fdump option is also in effect. =fillmem is in effect unless it is overridden. The default is =nodebug .  [cautionend]

=fillmem
=fi
specifies that when memory is allocated by the run-time library, it should be filled with the fill character 0xfc. This causes uninitialized variables to have unusual values (for example, an uninitialized int has a value of approximately --48,000,000), which increases the chance that the error will be detected. The default is =nofillmem , unless the debugger is used. When the debugger is used, =fillmem is the default.

Note:    The use of =fillmem forces the use of the =fdump linkage option. Also, the use of =fillmem substantially increases execution time.  [cautionend]

=hcsig
=hc
specifies that the library is to intercept computational signals ( SIGFPE , SIGSEGV , and SIGILL ) using SPIE or ESPIE. The default is =hcsig . Specifying =nohcsig prevents library handling of these signals. The following characteristics also pertain to =hcsig :

=htsig
=ht
specifies that the library is to intercept program termination signals ( SIGABRT and SIGABND ) using ESTAE under OS/390 or ABNEXIT under CMS. The default is =htsig . Specifying =nohtsig prevents library handling of these signals.

Note:    When =nohtsig is in effect, no traceback can be produced at program termination. Also, when the system function is used to call a TSO command, ESTAE is always used to protect TSO from the effects of an ABEND during this processing. This exit produces no messages and is in effect only during execution of the system function. Use of =nohtsig should seldom be required. The library's ABEND handling routine is written so that it does not interfere with other ABEND exits established by the caller of the C program or by assembler routines called from C.  [cautionend]

=multitask
=mu
specifies an alternate implementation of communication between a C program and the debugger or between a C program and other high-level languages. =multitask helps isolate the programs and languages from each other and reduces the chances that an error in one will cause the other to fail. However, use of =multitask causes additional overhead, and it is more suited for use during program development than in a production program. The default is =nomultitask . Refer to the SAS/C Compiler Interlanguage Communication Feature User's Guide for more information on the =multitask option.

Under OS/390, =multitask causes the C program, the debugger, and each non-C language to run as a separate task. The fork library function may not be used if =multitask is in effect.

=quit
=q
causes program execution to be abnormally terminated after any library warning message is generated. This can be useful for obtaining a dump in such a situation. If warnings are suppressed by the quiet function, the =quit option has no effect unless the =warning option is also specified. The default is =noquit .

=storage
=s
causes the library to create a storage analysis report at program termination or in the event of an ABEND. The report is identical to the output of the debugger's storage command. See the SAS/C Debugger User's Guide and Reference for detailed information about how to use the report.

If you are executing an all-resident module using the =storage option, you must also define the macro name ALLOW_TRANSIENT in the file that includes <resident.h> .

Under CMS, the report is written to STGRPT LISTING A1. In TSO or under OS/390 batch, the report is written to DDname STGRPT. Under the USS shell, the report is written to the file storage.out in the current directory. If the report is created at normal program termination, it is titled "Normal Termination Storage Report." If it is created during abnormal termination, it is titled "Abnormal Termination Storage Report."

=usage
=u
causes a storage usage report to be printed at program termination. This report can be used to determine the required stack size for a program that is to use the =minimal option. The default is =nousage .

=version
causes the release numbers associated with the resident and transient libraries to be displayed at program start-up. The display has the following format: 
LSCX056 SAS/C library release n.nnx  (resident)
                      release n.nnx  (transient)
where n.nnx is the release number. The release number of the resident library does not have to be the same as the release number of the transient library. This information can be helpful in determining library mismatches. See Chapter 1, "Introduction to the SAS/C Library," in SAS/C Library Reference, Volume 1 for information about using different releases of the Compiler and Library.

=warning
=w
forces library warning messages to be printed even if the quiet function is used by the program to suppress them. The =warning option also generates a traceback even when the program is cancelled, as by an OS/390 operator cancel or a CMS HX command. The traceback is ordinarily suppressed in this situation. This option may be useful for getting diagnostic information about a looping program. The default is =nowarning .

=xtrace
=x
causes a diagnostic to be printed, including a traceback, whenever a C++ exception is thrown. Only one traceback is printed for an exception, even if the exception is caught and rethrown.

=zeromem
=z
specifies that when memory is allocated by the run-time library, it should be filled with 0s. This causes uninitialized variables to be set to 0, which may allow erroneous programs to execute successfully. The default is =nozeromem .

Note:    Using =zeromem forces the use of the =fdump linkage option. Also, using =zeromem substantially increases execution time. If both =fillmem and =zeromem are specified, =fillmem is ignored.  [cautionend]


Program specification

To specify general run-time options in your program, initialize the integer variable _options with one or more bit flags to specifically request one or more options. The _options variable must be an external variable.

Include <options.h> to obtain the names of the flags for assignment to _options . The currently implemented options are as follows:
_ABDUMP produces a dump when an ABEND occurs.
_BTRACE prints a traceback with each diagnostic.
_DEBUG invokes the debugger.
_FILLMEM fills the memory with 0xfc when allocated.
_HCSIG handles computational signals.
_HTSIG handles abnormal termination signals.
_MULTITASK uses a multitasking debugger interface.
_QUIT terminates execution after a diagnostic.
_STORAGE produces storage corruption report after execution.
_USAGE prints a storage usage report after execution.
_VERSION prints the library version number.
_WARNING always prints the run-time warning messages.
_ZEROMEM indicates zero memory when allocated.

For example, the following code assigns flags to the _options variable: 

extern int _options = _BTRACE + _WARNING;
extern int _negopts = _NOHCSIG;

You can initialize the integer variable _negopts to reset (turn off) one or more options. Do not specify the same option for both the _options and _negopts variables; if you do, the result is undefined.

Include <options.h> to obtain the names of the flags for assignment to _negopts . The following are currently implemented options:
_NOABDUMP does not produce a dump when an ABEND occurs.
_NOBTRACE does not print a traceback with each diagnostic.
_NODEBUG does not invoke the debugger.
_NOFILLMEM does not fill the memory with 0xfc when allocated.
_NOHCSIG does not handle computational signals.
_NOHTSIG does not handle abnormal termination signals.
_NOMULTITASK does not use a multitasking debugger interface.
_NOQUIT does not terminate execution after a diagnostic.
_NOSTORAGE does not produce storage corruption report after execution.
_NOUSAGE does not print storage usage report after execution.
_NOVERSION does not print library version number.
_NOWARNING does not force printing of run-time warning messages.
_NOZEROMEM does not indicate zero memory when allocated.

For example, the following code prevents the library handling of computational signals: 

int  _negopts = _NOHCSIG;

Linkage Run-Time Options

Linkage options are a subset of the library options that specify which prolog and epilog code should be executed with your program. Even after link-editing your program, you have some flexibility choosing which prolog and epilog code is executed at function entry and return. The choice of linkage option can affect considerably how fast the program executes and how easy it is to debug. Note that the linkage options cannot be negated. The =inter option is the default linkage option.

Linkage Run-Time Options summarizes the linkage run-time options. The linkage options and their effects follow the table.

Linkage Run-Time Options
Specified on the Command Line
=fdump
=inter
=minimal
=optimize

=fdump
=fd
specifies that you want dump formatting support. This option is the most expensive and significantly increases function call overhead. However, it fully implements normal save-area chaining conventions and labels each save area with the name of the corresponding function, thereby improving dump readability.

=inter
=i
specifies that support for communication with assembler language, or other non-C code, is required. This is the default specification. In addition to providing interlanguage communication support, this option improves the reliability of the library's abend traceback. Use of this linkage option is recommended during program testing.

=minimal
=mi
specifies that a minimal form of program linkage is desired. Use of minimal linkage is recommended only for thoroughly tested and reliable programs for which performance is critical. Refer to =usage in General Run-Time Options and to =nnn/mmm in Memory Allocation Options for information on obtaining the stack size to specify when you use the =minimal option.

When minimal linkage is requested, a single area of memory is allocated for automatic storage when the program starts up; overflow of this area is not checked. If overflow occurs, random abends or overlays of the program or other data are to be expected.

Note:    Do not use this form of linkage for programs using recursive algorithms unless you know the upper bound to the amount of recursion required.  [cautionend]

Use of this option minimizes the overhead of function calls, producing significant savings. However, all of the restrictions described for optimized linkage also apply to minimal linkage. Also note that due to the difference in automatic storage layout when =minimal is specified, storing data outside the bounds of an array is more likely to overlay other data.

=optimize
=o
specifies that you want an optimized form of program linkage. When this option is specified, function call overhead is decreased. However, the following restrictions must be observed. If they are not observed, the effects are unpredictable.

Optimized linkage is recommended for production programs that meet the restrictions described above.

Note:    In some cases, use of optimized linkage may prevent the generation of an accurate traceback on abnormal termination.  [cautionend]


Program specification

You can initialize the character variable _linkage to specify a linkage option. Include <options.h> to obtain the names of the values for assignment to _linkage . The following are the currently implemented linkage options:
_FDUMP supports dump formatting.
_INTER supports linkage with other languages.
_MINIMAL suppresses stack overflow checking.
_OPTIMIZE supports optimized linkage.

The following is an example of assigning the _FDUMP option to the _linkage character variable: 

extern char _linkage = _FDUMP;

Memory Allocation Options

A run-time option can be specified on the command line to request the initial stack or heap allocation size, or both. The syntax of this option is as follows: 

=nnn/mmm

nnn is the starting stack size and mmm is the starting heap size. (The sizes can be expressed either as integers or as integers followed by an upper- or lowercase K.) To specify a stack size only, use =nnn (omit the slash). To specify a heap size only, use =/mmm (include the slash). The default heap size is 4K. The default starting stack size is 4K unless =minimal is specified, in which case the default is 32K.

Note:    If the program initializes the external variable _mneed to a non-zero value to indicate the use of the obsolete sbrk function, the mmm portion of the statement is interpreted as the size of the sbrk area rather than as the size of the heap.  [cautionend]

The following are examples for each operating system of commands that specify several run-time options:

Each example invokes the program exam . The library options =optimize and =nohtsig are specified, and an initial heap allocation of 80K is requested. Two arguments, which have the values nolist and sep(' ') , are passed to exam .

Program specification

These memory allocation options can be specified in the program as follows: 

int _stack   = value;
int _heap    = value;
int _mneed   = value;

You can initialize the integer _stack to a numeric value to request a specific initial allocation of stack space.

You can initialize the integer _heap to a numeric value to request a specific initial allocation of heap ( malloc ) space.

You can initialize the integer _mneed to a numeric value to request a specific initial allocation of sbrk space.

The following is an example of how to force a large heap allocation: 

int     _heap = 1024000;

Note that you can override a _heap or _mneed specification by using the =nnn/mmm option for the command line.

Program-only Options

This section describes several additional external variables that can be initialized by the program to request special library processing. These options are available only by using these external variables; that is, they cannot be specified at execution time via the command line.

You can initialize the integer variable _nio to any non-zero value to indicate that the C program performs no I/O with C library routines. The overhead of opening the standard files and loading I/O routines can thus be avoided. For example: 

int  _nio      = nonzero ;

You can initialize the integer variable _nlibopt to any non-zero value to suppress the use of library options or redirection on the command line. If _nlibopt is set, all tokens on the command line are passed to the program, even if they resemble run-time options. For example: 

int  _nlibopt  = nonzero ;

You can initialize the pointer _pgmnm to the address of a string literal to be used as the program name when no name can be obtained from the operating system. For example: 

char *_pgmnm   = string ;

stkabv and stkrels External Compiler Variables

Older versions of OS/390 were limited to running with 24-bit addresses, giving a maximum virtual address space of 16 megabytes. With the release of MVS/XA the addresses were increased to 31 bits giving a virtual address space maximum of 2 gigabytes. Certain portions of OS/390 (notably certain I/O subsystems) were not modified to accept 31-bit addresses, therefore programs wishing to utilize these services were forced to get storage below the 16M line to use as parameters when calling these functions. Prior versions of SAS/C allocated all stack memory from the area below the line to avoid the problems involved in calling old OS/390 services with 31-bit addresses.

In SAS/C Release 6.50, defining the external integer variable _stkabv in the source program (example: extern int _stkabv = 1; ) will indicate to the library to allocate stack space above the 16M line.

Note:    Setting the variable at run time will have no effect; it must be initialized to 1 as shown.  [cautionend]
However, some SAS/C library functions require their stack space be allocated below the line due to their use of auto storage for parameter lists and control blocks which still have a below-the-line requirement. These library routines have been identified, and either modified to remove the requirement, or changed to request that their own allocation of stack space be located below the 16M line. Release 6.50 includes a compiler option (STKBELOW) and a CENTRY macro parameter (STKBELOW=YES) to allow user code to request that its stack space be allocated below the line even if the _stkabv variable is defined as non-zero.

A new option allows the library to release stack space that is no longer needed. To free stack space, define the external integer variable _stkrels (example: extern int _stkrels = 1; ). This tells the library that, on return from a function, if an entire stack segment becomes unused, the segment should be returned to the operating system. This option is useful in long running programs that contain code paths that can occasionally become deeply nested, or in multi-tasking applications. Use of _stkrels and _stkabv guarantee that no stack space is allocated below the line if none is required by an executing routine.

Interleaved SYSOUT

Multi-tasking applications that share SYSOUT data sets between tasks may experience ABENDs when two or more tasks attempt to write to SYSOUT at the same time. A new external variable, _isysout, has been provided to prevent this type of ABEND.

_isysout
defining the external integer variable _isysout in the source program (for example, extern int _isysout = 1; ) indicates to the library that access to data sets with a SYSOUT type must be serialized. ABENDs may occur in a multitasking program (notably, ABEND S02A, reason x'0C') when more than one task attempts to write to a SYSOUT data set at the same time. The _isysout variable must be initialized to 1 in each task of a multitasking SAS/C application that could potentially write to a common SYSOUT data set.

This support is for OS/390 only, and OS/390 Name/Token services must be available at run time.


Chapter Contents
Previous
Next
Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.