IBM Mainframe Calls

The calls we present on the following pages are implemented only on IBM mainframe platforms.

tibems_SetCodePages()

Function

Purpose

Set code pages for string conversion on EBCDIC platforms (when non-default code pages are required).

C Declaration

tibems_status tibems_SetCodePages(

    char* host_codepage,

    char* net_codepage);

COBOL Call

CALL "tibems_SetCodePages"

USING BY REFERENCE host-codepage,

BY REFERENCE net-codepage,

RETURNING TIBEMS-STATUS

END-CALL.

Parameters

 

Parameter	Description
host_codepage	Set this code page as the native (EBCDIC) character encoding for the host computer.
net_codepage	Set this code page as the ASCII or UTF-8 character set for the network.

String Conversion

EMS software uses the operating system’s iconv() call to automatically convert strings within messages. Conversion occurs only as needed:

●	Programs running in EBCDIC environments represent all strings using an EBCDIC code page (called the host code page). Before sending a message, the EMS client library converts its strings to an ASCII or UTF-8 character set (the network code page).

●	Conversely, when a message arrives from the network, the EMS client library converts its strings to the EBCDIC host code page before presenting the message to the program.

Remarks

This call sets the host and network code pages for string conversions in EBCDIC environments.

Call this function when the system code pages differ from the EMS default code pages (see the table of Default Code Pages). Throughout an enterprise, all sending and receiving programs must use the same code pages.

Both arguments are string names of code pages. To determine valid code page names for your operating system, see documentation from the operating system vendor.

Programs may call this function at most once. The call must precede the first call to any message function, and the arrival of the first message from the network.

 

Default Code Pages

To use a default code page, programs may supply NULL for either parameter. Using the default code pages in both parameter positions has the same effect as not calling this function at all.

 

Default Host Code Page	Default Network Code Page
"IBM-1047"	"ISO8859-1"

See Also

Strings and Character Encodings

tibx_MVSConsole_SetConsumer()

Function

Purpose

Exit from a blocking listener.

C Declaration

tibx_MVSConsole_SetConsumer(

    void* pConsole,

    tibemsMsgConsumer tibemsMsgConsumer,

    char* tibems_MVS_BreakFunction);

 

signed long int tibems_MVS_BreakFunction(

   void* pConsole );

COBOL Call

SET WS-PROCEDURE-PTR TO ENTRY 'tibems_MVS_BreakFunction'

 

CALL "tibx_MVSConsole_SetConsumer"

     USING BY VALUE   pConsole,

           BY VALUE   tibemsMsgConsumer,

           BY VALUE   pFunction,

           RETURNING  tibems-status

END-CALL.

 

pConsole has usage pointer. Before this call, you must set the entry to the MVS break function.

Parameters

 

Parameter	Description
pConsole	Set the consumer of this MVS console object.
tibemsMsgConsumer	Use this message consumer.
pFunction	In COBOL, use this tibems_MVS_BreakFunction function address.
tibems_MVS_BreakFunction	In C, use this break function name.

Remarks

Programs in single-threaded environments (such as COBOL) need a way to interrupt blocking receive calls (such as tibemsMsgConsumer_Receive).

This call is available only in MVS.

After registering this function in COBOL, a console stop or shut command causes the receive call to return with a status code TIBEMS_USER_INTR (54).

See Also

tibemsMsgConsumer_Receive on page 168

tibx_MVSConsole_Create() on page 532

tibx_MVSConsole_Create()

Function

Purpose

Create or destroy an MVS console.

C Declaration

signed long int tibx_MVSConsole_Create (

    void** pConsole,

    char** pConsoleMsg,

    Console_Response pCallBack)

 

signed long int tibx_MVSConsole_Destroy(

    void* pConsole );

COBOL Call

CALL "tibx_MVSConsole_Create"

     USING BY REFERENCE pConsole,

           BY REFERENCE pConsoleMsg,

           BY VALUE     TIBEMS-NULLPTR,

           RETURNING    tibems-status

END-CALL.

 

CALL "tibx_MVSConsole_Destroy"

     USING BY VALUE pConsole,

     RETURNING tibems-status

END-CALL.

 

pConsole and pConsole-Msg have usage pointer.

Parameters

 

Parameter	Description
pConsole	The create call stores the MVS console handle in this location. The destroy call destroys this MVS console.
pConsoleMsg	When the return status code is non-zero, the function stores an error message in this location.
pCallBack	C programs define this callback function to receive the results of MVS console commands.

Remarks

Some consumer application programs wait indefinitely for messages to arrive. You can use this function in conjunction with tibems_MVS_BreakFunction to arrange console input to such programs, in order to interrupt them from waiting to receive a message, so they can exit cleanly (see tibx_MVSConsole_SetConsumer() on page 531).

This call is available only in MVS.

C programs can receive console command results through a callback function. COBOL programs cannot receive console command results, but can react to the MVS stop and shut commands.

See Also

tibemsMsgConsumer_Receive on page 168

tibx_MVSConsole_SetConsumer() on page 531