Open System Services Programmer's Guide

Procedures That Return Both a Return Value and a Condition Code
Procedures that return both a return value and a condition code cannot be called directly from an
OSS program, so you must write a “jacket” procedure in pTAL that can be called from a C program.
This jacket procedure can contain only the code required to call the desired Guardian procedure,
and the jacket procedure must be callable from an OSS program. Most Guardian procedures, but
not all, can be called from an OSS program.
You will probably not need to call procedures that return both a return value and a condition code,
but if you do, see the C/C++ Programmer’s Guide for details.
Guardian C Functions
The native C run-time library supports both the OSS and Guardian environments, which means
that there is a single library for functions that are part of both APIs. Most differences that exist in
behavior of the functions in the two APIs for TNS programs no longer exist for native programs.
For information about interoperability between the Guardian and OSS APIs in native processes,
see Table 78: API Interoperability in Native Processes (Functions a through m) (page 506).
There are a few functions that are specified by HP and can be called only from a Guardian module,
which means you must call them from a separate module compiled for the Guardian environment.
For information on these functions, see the Open System Services Library Calls Reference Manual
or the Guardian Native C Library Calls Reference Manual.
Considerations for TNS Programs
To call Guardian C functions from an OSS TNS program in which the main() module is compiled
to run in the OSS environment, you must write the function calls in a separate module compiled
for the Guardian environment and link (bind) that module with the OSS program. The Guardian
C Run-Time Library contains the functions in the ISO/ANSI C standard with HP extensions. In many
cases, C functions of the same name in the OSS and Guardian APIs behave identically, but in
some cases they do not. Also note that not all functions in each API can be called from each
environment. Before writing mixed-module programs, review Table 78: API Interoperability in
Native Processes (Functions a through m) (page 506), which describes the interoperability between
the Guardian and OSS APIs in TNS processes.
Using Guardian C functions is an alternative to using Guardian procedures when you cannot
accomplish a task with OSS functions. Because of the mixed-module programming and API
interoperability considerations, it is easier to use Guardian procedures. However, if you are more
familiar with the C language than with Guardian procedures, you might want to use Guardian C
functions. For example, if you want to open a Guardian file and then just read and write to it, this
can be done equally well using Guardian procedures or Guardian C functions.
However, you need to look at the whole set of required operations to determine whether you can
implement them all using Guardian C functions or that there would be a mix of Guardian procedures
and Guardian C functions. If there is a mix, it would be easier to use all Guardian procedures.
For example, if your goal is to open a Guardian file and later use FILE_GETINFOLISTBYNAME_
to get information about it, you could open the file with the Guardian C open() function. Then
you have to use another Guardian C function to translate the file descriptor returned by open()
to a filename, which is required by FILE_GETINFOLISTBYNAME_.
Compiling and Linking Separate Guardian Modules
To call a Guardian module from an OSS program, you must compile and link that module with
the OSS program in which the main() module is compiled for the OSS environment. The separate
Guardian module must be compiled with the SYSTYPE pragma set to GUARDIAN. This gives you
the Guardian, not the OSS, API. The default SYSTYPE pragma for programs compiled with the
c89 or c99 utility is SYSTYPE OSS.
To compile a module with the SYSTYPE pragma set to GUARDIAN, specify the -Wsystype flag
of the c89 or c99 utility.
42 Overview of the OSS Programming Environment