PowerBuilder Interface

This chapter describes functions used by a PowerBuilder interface with examples.

1. Overview

Since PowerBuilder treats data as a string and does not use a pointer, it cannot use Tmax client libraries directly. Therefore, Tmax provides tmax.pbd, a user object, to maintain each data’s type and efficiently use PowerObject provided by PowerBuilder.

DataWindow is PowerBuilder’s PowerObject that keeps data information and offers various data presentation functions. DataWindow is a very useful feature of the application development software package.

However, developers face difficulties using DataWindow because the data formats provided in the client libraries are incompatible with it. To address this issue, tmax.pbd converts the result data into formats that DataWindow can use without modification, allowing developers to manipulate data more easily.

tmax.pbd provides the following functions.

Function Description

f_data

Generates a data string.

f_datadel

Generates a data string.

f_fdata

Generates a data string.

f_fdatadel

Generates a data string.

f_form

Generates a Form string.

f_getdata

Gets data in a specific position among output in the Form format and returns the data as a string.

isblocked

Checks whether a service is in blocking state.

pb_etpcall

Processes image data.

pb_getunsold

Receives unrequested messages.

pb_IsBlocked

Checks whether a service is in blocking state.

pb_reset

Ends a current connection immediately.

pb_tmaxreadenv

Reads information about a system to connect from a file and configures environment variables by using the information.

pb_tpacall

Calls a service asynchronously.

pb_tpalloc

Allocates a buffer with a type specified using itype and returns the buffer’s address.

pb_tpbroadcast

Sends a message to a specified client.

pb_tpcall

Calls a service synchronously.

pb_tpcallw

Synchronously calls a Tmax service by using DataWindow.

pb_tpcancel

Cancels a descriptor returned by pb_tpacall().

pb_tpcommit

Commits a transaction.

pb_tpconnect

Connects to an interactive service.

pb_tpconv

Sends and receives messages to and from an interactive service specified with the 1st parameter.

pb_tpdiscon

Forcibly ends a connection for communication and causes the TPEV_DISCONIMM event.

pb_tpend

Ends a connection to a Tmax system.

pb_tpfcall

Receives input data from a file and saves result data to a file.

pb_tpfree

Frees buffers that were allocated by using pb_tpalloc().

pb_tpget

Reads data corresponding to an address specified in the 1st parameter to a buffer specified in the 2nd parameter as much size as a value specified in the 3rd parameter.

pb_tpgetrply

Receives a reply to a request sent from pb_tpacall().

pb_tpgetunsol

Processes unrequested messages received.

pb_tpput

Saves the data specified in the 2nd parameter to the address specified in the 1st parameter based on the size specified in the 3rd parameter.

pb_tprecv

Receives data in interactive communication.

pb_tpreset

Immediately ends a currently established connection.

pb_tpsend

Sends data in interactive communication.

pb_tpset_timeout

Changes blocking timeout (service timeout) that is set in a server.

pb_tpsetunsol

Enables to receive unrequested messages.

pb_tpstart

Connects to Tmax.

pb_tptobackup

Connects to a backup system when a client accesses a Tmax system.

pb_tx_begin

Begins a global transaction.

pb_tx_commit

Commits a transaction.

pb_tx_rollback

Rolls back a transaction.

pb_tx_set_commit_return

Determines the time to commit a global transaction by using a parameter.

pb_tx_set_transaction_control

Determines whether to start a new transaction by using a parameter before pb_tx_commit() or pb_tx_rollback() is returned.

pb_tx_set_transaction_timeout

Sets transaction timeout.

pb_uotmax_ver

Queries the version of tmax.pbd.

pb_tx_info

Queries information about global transactions.

tp_abort

Aborts a transaction.

tp_acall

Asynchronously calls a service.

tp_begin

Begins a global transaction.

tp_broadcast

Sends a message to a specified client.

tp_call

Synchronously calls a Tmax service.

tp_cancel

Cancels a descriptor returned by tp_acall().

tp_commit

Commits a transaction.

tp_connect

Connects to an interactive service.

tp_conv

Sends and receives messages to and from a specified interactive service

tp_discon

Forcibly ends a connection for communication and causes the TPEV_DISCONIMM event.

tp_fcall

Synchronously calls a Tmax service.

tp_getrply

Receives data in asynchronous communication.

tp_init

Connects to Tmax.

tp_recv

Receives data in interactive communication.

tp_send

Sends data in interactive communication.

tp_subscribe

Receives messages that are transferred from a server through tppost().

tp_term

Ends a connection to a Tmax system.

tp_unsubscrib

Turns off the configuration set with tp_subscribe() or tp_setunsol() to receive messages from a window.

tpbegin

Performs both the pb_tx_set_transaction_timeout() and pb_tx_begin() functions simultaneously.

tuxcall

Synchronously calls a Tmax service.

tuxedo_compat

Provides compatibility with Tuxedo libraries for some APIs.

tuxreadenv

Reads information about a system to connect from a file and configures environment variables by using the information.

2. Functions

2.1. f_data

Generates a data string from modified rows in DataWindow, DataWindowChild, or DataStore. To generate a string, this function separates a column name and data by using a tab character ("~t") and divides each column name and data pair by using a newline character ("~n"). The generated string can be used as an input in pb_tpcall. Only the modified rows among the data in the DataWindow, DataWindowChild, and DataStore are retrieved.

  • Prototype

    f_data ( {DataWindow | DataWindowChild | Datastore} ds_in )
returns string

  • Parameter

    Parameter Description

    ds_in

    PowerBuilder object to be used as an input.

  • Return value

    String in which column names and data in DataWindow, DataWindowChild, or DataStore are delimited by tab and newline.

  • Example

    string itype, input, form[], output[]

...
itype = "STRING~t~n"
input = uo_tmax.f_data(dw_input) + & "~n”

...
ret = uo_tmax.pb_tpcall("TOUPPER", itype, input, form[], output[])
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    f_datadel(), f_fdatadel(), pb_tpcall(), pb_tpacall(), pb_tpconnect()

2.2. f_datadel

Generates a data string from data in DeletedBuffer of DataWindow. To generate a string, this function separates a column name and data in DataWindow, DataWindowChild, or DataStore by using a tab character ("~t") and divides each column name and data pair by using a newline character ("~n"). The generated string can be used as an input in pb_tpcall.

f_data() generates a string from data that includes data in DeletedBuffer if the dwDelBuf variable is TRUE. f_datadel() generates a string only from data in DeletedBuffer regardless of the variable. DeletedBuffer temporarily saves data to be deleted when DeleteRow() is used. f_datadel() normally operates only when DataWindow can update DeletedBuffer.

Note the following to save data in DeletedBuffer when DeleteRow() is used.

– 'Allow Update' (in [Rows] > [Update Properties..] menu in PowerBuilder) for DataWindow must be selected.

– If ImportString is executed and then DeleteRow is executed without executing ResetUpdate, a corresponding row will not be saved in DeleteBuffer.

  • Prototype

    f_datadel ( {DataWindow | DataWindowChild | Datastore} ds_in )
returns string

  • Parameter

    Parameter Description

    ds_in

    PowerBuilder object (DataWindow, DataWindowChild, and DataStore are available) to be used as an input.

  • Return value

    String in which data in DeletedBuffer of DataWindow, DataWindowChild, or DataStore are delimited by tab and newline.

  • Example

    string itype, input, form[], output[]
...
itype = "STRING~t~n"
input = uo_tmax.f_datadel(dw_input) + & "~n"
...
ret = uo_tmax.pb_tpcall("TOUPPER", itype, input, form[], output[])
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    f_fdata(), f_fdatadel(), pb_tpcall(), pb_tpacall(), pb_tpconnect()

2.3. f_fdata

Generates a data string from modified rows in DataWindow, DataWindowChild, or DataStore. This function writes the string to a file specified by filehandle in the same format as f_data, which separates column names and data by a tab character ("~t") and each column name and data pair by a newline character ("~n").

  • Prototype

    f_fdata ( {Datastore|DataWindow|DataWindowChild} ds_in, integer filehandle )
returns integer

  • Parameter

    Parameter Description

    ds_in

    PowerBuilder object (DataWindow, DataWindowChild, and DataStore are available) to be used as an input.

    filehandle

    File separator used for temporary files. The integer filehandle, a string specifying the field name to retrieve from the data returned after a server call, can be used as the input temporary file, the fourth parameter in pb_tpfcall().

  • Return value

    Return value Description

    0

    Function call succeeded.

    -1

    Function call failed. (For example, data could not be written in a file.)

  • Example

    ...
InputFile ="c:\temp\fdata0.txt"
InputFile = FileOpen(InputFile, StreamMode!, Write!, LockReadWrite!, Replace!)
...
uo_tmax.f_fdata(dw_input, InputFile)
if FileClose(InputFile) <> 1 then
   error processing
   ...
end if
...
if uo_tmax.tp_fcall(input, form, output, inputfilename, fform, foutput) = -1 then
   error processing
   ...
end if
...

  • Related functions

    f_data(), f_datadel(), f_fdatadel()

2.4. f_fdatadel

Generates a data string from rows saved in DeletedBuffer of DataWindow, DataWindowChild, or DataStore and writes the string to a file specified by filehandle. The method of generating a string is the same as in f_data().

Note the following to save data in DeletedBuffer when DeleteRow() is used.

– 'Allow Update' (in [Rows] > [Update Properties..] menu in PowerBuilder) for DataWindow must be selected.

– If ImportString is executed and then DeleteRow is executed without executing ResetUpdate, a corresponding row will not be saved in DeleteBuffer.

  • Prototype

    f_fdatadel ( {Datastore|DataWindow|DataWindowChild} ds_in, integer filehandle )
returns integer

  • Parameter

    Parameter Description

    ds_in

    PowerBuilder object (DataWindow, DataWindowChild, and DataStore are available) to be used as an input.

    filehandle

    File separator used for temporary files.

  • Return value

    Return value Description

    0

    Function call succeeded.

    -1

    Function call failed. (For example, data could not be written in a file.)

  • Related functions

    f_data(), f_datadel(), f_fdata()

2.5. f_form

Generates a Form string that can be used as the 4th parameter of pb_tpcall() from column names in DataWindow, DataWindowChild, and DataStore. To generate a string, this function separates column names by using a newline character ("~n") and adds a newline character ("~n") at the end.

  • Prototype

    f_form ( {Datastore|DataWindow|DataWindowChild} ds_in)
returns string

  • Parameter

    Parameter Description

    ds_in

    PowerBuilder object (DataWindow, DataWindowChild, and DataStore are available) to be used as an input.

  • Return value

    String in which column names in DataWindow, DataWindowChild, or DataStore are delimited by newline.

  • Example

    string itype, input, form[], output[]
...
itype = "STRING~t~n"
input = uo_tmax.f_data(dw_input) + & "~n"
form[1] = uo_tmax.f_form(dw_input)
...
ret = uo_tmax.pb_tpcall("TOUPPER", itype, input, form[], output[])
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpcall(), pb_tpgetrply(), pb_tprecv(), pb_tpconv()

2.6. f_getdata

Gets data in arg_col_name of an arg_row-th array among output in the Form format and returns the data as a string.

  • Prototype

    f_getdata ( string form, string odata, integer arg_row, string arg_col_name )
returns string

  • Parameter

    Parameter Description

    form

    Has the format of a service result, odata. For a STRUCT buffer, odata consists of members of a used structure, and for a FIELD KEY buffer, it consists of names of used fields. Members or field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    arg_row

    Row in which a string to find is located.

    arg_col_name

    Column in which a string to find is located.

  • Return value

    String found.

  • Example

    string itype, input, form[], output[]
...
itype = "STRING~t~n"
input = uo_tmax.f_data(dw_input) + & "~n"
form[1] = uo_tmax.f_form(dw_input)
...
ret = uo_tmax.pb_tpcall("TOUPPER", itype, input, form[], output[])
if ret < 0 then
   error processing
   ...
end if
...

2.7. isblocked

Checks whether a service is being called (blocking state).

When a service is being called, the service cannot be called again and another service cannot be called. If a button for calling the service or another service is clicked, an error will occur. Therefore, when a button for calling a service is clicked, this function must be called first and a message to wait must be sent if a service is being called.

  • Prototype

    isblocked ()
returns integer

  • Return value

    Return value Description

    1

    Indicates the blocking state.

  • Example

    ...
ret = uo_tmax.isBlocked()
if ret = 0 then
   MessageBox("pb_isBlocked", "NO BLOCK " + string(uo_tmax.tperrno))
else
   MessageBox("pb_isBlocked", "BLOCKING")
end if
...

  • Related functions

    pb_isblocked()

2.8. pb_etpcall

Can be used in the same way as in pb_tpcall(). This function has a feature of processing image data as well as features of pb_tpcall(). To process image data, a FIELD KEY buffer and a specific field name must be used. To send and receive image data, a file must be specified by using a field named "FIFENAM" and "NEWFILE" respectively. Actual image data is transferred to a field named "TP_BITMAP" in the CARRAY format.

When sending image data, the name of a file to be sent must be specified in input with a field named "FILENAM". The field name is used in a client library to read image data from the specified file and send the data to a server by saving the data in a field named "TP_BITMAP". The size of image data can exceed 4 MB.

When receiving image data from a server, the name of a file in which the data will be saved must be specified in idata with a field named "NEWFILE". The data is sent with a field named "TP_BITMAP" in a service program, and the data is saved in the specified file in a client library. Data with a field named "NEWFILE" must exist in a receive buffer.

  • Prototype

    pb_etpcall(string svcname, string itype, string idata, string form[],
           ref string odata[])
returns integer

  • Parameter

    Parameter Description

    svcname

    Name of a service to be called.

    itype

    Format of string data in a buffer. Strings are delimited by a tab character ("~t") and a line is ended with a newline character ("~n").

    idata

    Format of string data in a buffer that will save data to be processed. Input data is delimited by a tab character ("~t") and a line is ended with a newline character ("~n").

    form

    Has the format of a service result, odata. For a STRUCT buffer, odata consists of members of a used structure, and for a FIELD KEY buffer, it consists of names of used fields. Members or field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    The following describes Tmax’s instance variables. The flags and timeout variables are set before a service is called, and the other variables are set after a service is called.

    Variable Description

    msg

    Message sent from a service program.

    tperrno

    Buffer in which an error code will be saved if an error occurs.

    tpurcode

    Buffer in which a user code (the 2nd argument of tpreturn()) sent from a server will be saved.

    flags

    The following flags can be used in pb_tpcall().

    • TPNOTRAN: used to call a service in non transaction mode.

    • TPNOCHANGE: guarantee that types of a buffer for initial allocation and a buffer for responses are identical.

    • TPNOBLOCK: used to call a service in non blocking mode.

    • TPNOTIME: ignore blocking timeout.

    [Note]

    tuxedo_compat(true) operates according to flags. For more information, refer to tuxedo_compat().

    timeout

    Blocking timeout used in pb_tx_set_transaction_timeout().

  • Return value

    Return value Description

    0

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Example

    long ret
string itype, idata, form[], odata[]
string FileName = "c:\abc.bmp"

if isnull(sle_1.text) or sle_1.text = '' then
   error processing
   ...
end if

itype = "FML~t~n"
/*To upload FILE, a file name is set in the FILENAM field.*/
idata = "FILENAM~t" + FileName + "~n"

form[1] = "~n"
odata[1] = space(1024)

ret = uo_tmax.pb_etpcall("IMGSAVE", itype, idata, form[], odata[])

if ret < 0 then
   error processing
   ...
end if

  • Related functions

    f_data(), f_datadel(), f_form(), tuxedo_compat()

2.9. pb_getunsold

Receives unrequested messages. Since PowerBuilder cannot access memory within a library, it needs to secure memory to receive unrequested messages and transfer the messages from the memory to a library.

When unrequested messages are transferred, the message length and mid are sent to a window set by pb_tpsetunsol(). The window secures as much memory as the length and saves data in the memory when pb_getunsold() is called. To receive unrequested messages by using pb_tpsetunsol() and pb_getunsold(), flags, an instance variable of u_tmax, must be set to TPUNSOL_HND and then pb_tpstart() must be called.

  • Prototype

    pb_getunsold ( ref string odata, integer len, unsignedinteger mid )
returns integer

  • Parameter

    Parameter Description

    odata

    Buffer that will save unrequested messages to be received.

    len

    Length of unrequested messages to be received.

    mid

    Message delimiter.

  • Return value

    Return value Description

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    tperrno is set to one of the following values.

    Error Code Description

    TPEINVAL

    An argument is invalid. rcvbuf is NULL, or mid is less than 0.

    TPEITYPE

    The size of memory secured by PowerBuilder is smaller than that of the received data.

    TPEOTYPE

    Received data does not exist or is invalid.

    TPEMATCH

    No data corresponds to the specified mid.

  • Example

    uo_tmax.flags = uo_tmax.TPUNSOL_HND
...
ret = uo_tmax.pb_tpsetunsol ( HANDLE(this), "", 1025, uo_tmax.TPBROADCAST )
if ret = -1 then
   error processing
   ...
end if
...
unsoldata = space(1024)
ret = uo_tmax.pb_getunsold(unsoldata, rlen, 1025)
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpsetunsol()

2.10. pb_IsBlocked

Checks whether a service is being called (blocking state).

When a service is being called, the service cannot be called again and another service cannot be called. If a button for calling the service or another service is clicked, an error will occur. Therefore, when a button for calling a service is clicked, this function must be called first and a message to wait must be sent if a service is being called.

  • Prototype

    pb_isblocked ()
returns integer

  • Return value

    Return value Description

    1

    Indicates the blocking state.

  • Example

    ...
ret = uo_tmax.pb_isBlocked()

if ret = 0 then
    MessageBox("pb_isBlocked", "NO BLOCK " + string(uo_tmax.tperrno))
else
    MessageBox("pb_isBlocked", "BLOCKING")
end if
...

  • Related functions

    isBlocked()

2.11. pb_reset

Ends a current connection immediately. Since a main reason of the TPESYSTEM error in a client module is a network error, it is recommended to reconnect to a Tmax system. For this, a current connection is ended by using this function and then a service is requested again or a Tmax system is reconnected.

  • Prototype

    pb_reset ()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    tperrno is set to one of the following values.

    Error Code Description

    TPESYSTEM

    A Tmax system error occurred. Detailed information is recorded in a log file.

    TPEOS

    An OS error occurred.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax
uo_tmax.usr_name = 'tmaxclient'
uo_tmax.clt_name = 'cilent01'
uo_tmax.dom_pwd = 'tmax'
uo_tmax.usr_pwd = 'client01'
uo_tmax.flags = uo_tmax.TPUNSOL_IGN
...
ret = uo_tmax.pb_tpstart()
if ret < 0 then
   error processing
   ...
end if
...
ret = uo_tmax.pb_tpreset()
if ret < 0 then
   error processing
   ...
endif

2.12. pb_tmaxreadenv

Reads information about a system to connect from a file and configures environment variables by using the information. This function must be called before trying to connect to a Tmax system because it configures environment variables used to connect the Tmax system. The environment variables must be registered in the Tmax system in advance. By referring to the environment variables, a Tmax system can be connected through pb_tpstart().

A configuration file that defines environment variables varies by OS. In UNIX csh and ksh are defined in <.cshrc> and <.profile> respectively, while in DOS they are defined in <autoexec.bat>. If multiple systems need to be connected, the client can switch between systems as required. Environment variables can be used for management. Since multiple systems cannot be configured only with environment variables,they must be registered in a file and then this file must be used for configuration.

[TMAX]
TMAX_HOST_ADDR=168.126.185.131
TMAX_HOST_PORT=8800
SDLFILE=C:\tmax\sample\sdl\tmax.sdl
FDLFILE=C:\tmax\sample\fdl\tmax.fdl
TMAX_CONNECT_TIMEOUT=2

  • Prototype

    pb_tmaxreadenv(string env_file, string section)
returns integer

  • Parameter

    Parameter Description

    env_file

    Name of a file that contains information about a system to be connected. The file must be text, and included information must be set in a valid format.

    section

    Identifier for information registered in a configuration file. This allows to identify each system when multiple systems are configured.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tmaxreadenv in Tmax Reference Guide.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax
...
ret = uo_tmax.pb_tmaxreadenv("./tmax.env", "TMAX")
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpstart(), pb_tpend()

2.13. pb_tpacall

Calls a service asynchronously. In asynchronous communication, a client can process its jobs after requesting a service and receive a response when it wants to receive. After pb_tpacall() is called to request a service, the function is returned immediately to allow a client to process other jobs. After pb_tpgetrply() is called to receive a response, the function is blocked and waits until a response is received or timeout occurs. pb_tpgetrply() uses a descriptor returned by pb_tpacall().

  • Prototype

    pb_tpacall ( string svcname, string itype, string idata )
returns integer

  • Parameter

    Parameter Description

    svcname

    Name of a service to be called.

    itype

    Format of string data in a buffer. Strings are delimited by a tab character ("~t") and a line is ended with a newline character ("~n").

    idata

    Format of string data in a buffer that will save data to be processed. Input data is delimited by a tab character ("~t") and a line is ended with a newline character ("~n").

  • Return value

    Return value Description

    cd greater than or equal to 1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tpacall in Tmax Reference Guide.

  • Example

    string input, itype, form[], output[]
int length, cd, ret

length = len(before.text)

itype = "STRUCT~tkstrdata~n"
input = string(length) + "~t" + before.text + "~n"
form[1] = "len~n" + "sdata~n" + "~n"
form[2] = "~n"
output[1] = space(1024)

cd = uo_tmax.pb_tpacall("SYNC", itype, input)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tpgetrply(cd, form, output)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    pb_tpgetrply(), pb_tpcancel(), pb_tpcall()

2.14. pb_tpalloc

Allocates a buffer with a type specified using itype and returns the buffer’s address. For this, pb_tpalloc() calls tpalloc() of <tmax4gl.dll>. The isubtype and ilen parameters can be specified optionally according to a buffer type. A returned address can be used as an argument of the buf parameter of pb_tpput and pb_tpget functions and newly created pb_b~ functions.

If a specified buffer type can use a subtype, isubtype must be specified. If not, isubtype is ignored and usually 0 is used. The size of an allocated buffer is more than 1,024 bytes (the default value) typically.

For more information about pb_tpalloc(), refer to tpalloc in Tmax Reference Guide.

  • Prototype

    pb_tpalloc ( string itype, string isubtype, long ilen )
returns long

  • Parameter

    Parameter Description

    itype

    Type of a buffer to be allocated (e.g., 'STRUCT' , 'STRING', 'CARRAY', 'FIELD').

    isubtype

    Subtype of the specified buffer.

    ilen

    Size of a buffer to be allocated. (Default value: 1024)

  • Return value

    Return value Description

    address

    Function call succeeded.

    0

    Function call failed. The error code is set in tperrno.

  • Error

    tperrno is set to one of the following values.

    Error Code Description

    TPEINVAL

    An argument is invalid (e.g., NULL type).

    TPENOENT

    The type is unknown or a subtype.

    This error will occur if a sub type (tag name of a structure) does not exist in SDLFILE for a STRUCT buffer, or if a client does not call tpstart() or allocates a STRUCT buffer by using tpalloc() before calling tpstart().

    TPESYSTEM

    A Tmax system error occurred. Detailed information is recorded in a log file.

    TPEOS

    Memory cannot be allocated in OS.

    TPEOTYPE

    A structure buffer was requested by a server, but a structure file was not compiled by the server.

  • Example

    long ret
long buf
u_tmax uo_tmax
uo_tmax = CREATE u_tmax

uo_tmax.usr_name = 'tmaxclient'
uo_tmax.clt_name = 'cilent01'
uo_tmax.dom_pwd = 'tmax'
uo_tmax.usr_pwd = 'client01'
uo_tmax.flags = uo_tmax.TPUNSOL_IGN
...
ret = uo_tmax.pb_tpstart()
if ret < 0 then
   error processing
   ...
end if
...
buf = uo_tmax.pb_tpalloc("CARRAY", "", 40000)
...

2.15. pb_tpbroadcast

Sends a message to a specified client.

  • Prototype

    pb_tpbroadcast ( string nodename, string usrname, string cltname, string data )
returns integer

  • Parameter

    Parameter Description

    nodename

    Name of a node that includes a client to which a message will be sent.

    usrname

    Name of a user to which a message will be sent. The argument must be the same as the usr_name value set for pb_tpstart().

    cltname

    Name of a client to which a message will be sent. The argument must be the same as the clt_name value set for pb_tpstart().

    data

    Buffer that will save data to be processed. Input data is deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    nodename, usrname, and cltname are logical names used to select a target client. A wildcard character can be used for the names; a question mark (?) and an asterisk (*) can be included in usrname and cltname, and an asterisk (*) can be used instead of a nodename value. In addition, NULL can be used to express all clients.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tpbroadcast in Tmax Reference Guide.

  • Example

    string nodename, usrname, cltname, data
int ret
...
nodename = "tmax"
usrname = "*"
cltname = "*"
data = sle_input.text
ret = uo_tmax.pb_tpbroadcast(nodename, usrname, cltname, data)
if ret < 0 then
   error processing
   ...
end if
...

2.16. pb_tpcall

Calls a service synchronously. In synchronous communication, a client requests a service and waits until receiving a result. Data to be processed is saved in a buffer specified with idata, a service specified with svcname is called, and then the service’s result is saved in a specified column in Form as odata.

  • Prototype

    pb_tpcall(string svcname, string itype, string idata, string form[],
          ref string odata[])
returns integer

  • Parameter

    Parameter Description

    svcname

    Name of a service to be called.

    itype

    Format of string data in a buffer. Strings are delimited by a tab character ("~t") and a line is ended with a newline character ("~n").

    • STRUCT buffer type

       itype = "STRUCT~tstruct_name~n"

    • STRING buffer type

      itype ="STRING~t~n"

    • FIELD KEY buffer type

      itype = "FIELD~t~n"

    idata

    Format of string data in a buffer that will save data to be processed. Input data is deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    form

    Has the format of a service result, odata. For a STRUCT buffer, odata consists of members of a used structure, and for a FIELD KEY buffer, it consists of names of used fields. Members or field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    The following describes Tmax’s instance variables. The flags and timeout variables are set before a service is called, and the other variables are set after a service is called.

    Variable Description

    msg

    Message sent from a service program.

    tperrno

    Buffer in which an error code will be saved if an error occurs.

    tpurcode

    Buffer in which a user code (the 2nd argument of tpreturn()) sent from a server will be saved.

    flags

    The following flags can be used in pb_tpcall().

    • TPNOTRAN: used to call a service in non transaction mode.

    • TPNOCHANGE: guarantee that types of a buffer for initial allocation and a buffer for responses are identical.

    • TPNOBLOCK: used to call a service in non blocking mode.

    • TPNOTIME: ignore blocking timeout.

    timeout

    Blocking timeout used in pb_tx_set_transaction_timeout().

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Error

    For detailed information about error codes, refer to tpcall in Tmax Reference Guide.

  • Example

    • When a STRUCT buffer is used

      string itype, input, form[], output[]
int ret
itype = "STRUCT~t" + "kstrdata~n"
input = string(len(before.text)) + "~t" + before.text + "~n"
form[1] = "len" + "~n" + &
 "sdata" + "~n" + &
"~n"
form[2] = "~n"
output[1] = space(1024)

uo_tmax.flags = uo_tmax.TPNOCHANGE
uo_tmax.timeout = 50

ret = uo_tmax.pb_tpcall("SYNC", itype, input, form, output)
if ret < 0 then
   messagebox("ERROR","tpcall Failed : Error Code =" + string(uo_tmax.tperrno))
   return
end if

afterlen.text = uo_tmax.f_getdata(form[1], output[1], 1, "len")
afterdata.text = uo_tmax.f_getdata(form[1], output[1], 1, "sdata")

    • When a FIELD KEY buffer is used

      long ret
string itype, input, form[], output[]

if isnull(sle_1.text) or sle_1.text = '' then
...
end if

itype = "FIELD~t~n"
input = "INPUT~t" + sle_1.text + "~n"

form[1] = "OUTPUT~n~n"
form[2] = "~n"
output[1] = space(40)

ret = uo_tmax.pb_tpcall("FDLTOUPPER", itype, input, form[], output[])
if ret < 0 then
    error processing
    ...
end if
...

  • Related functions

    pb_tpacall(), pb_tpgetrply()

2.17. pb_tpcallw

Synchronously calls a Tmax service by using DataWindow. A service is called by using PowerObject specified with iobject. The service’s result is saved in PowerObject specified with oobject. This function uses FIELD buffers.

  • Prototype

    pb_tpcallw ( string svcname, powerobject iobject[], powerobject oobject[] )
returns integer

  • Parameter

    Parameter Description

    svcname

    Name of a service to be called.

    iobject

    PowerObject used to call a service.

    oobject

    PowerObject in which a result will be saved.

    The following describes objects that can be used as input.

    Object Description

    DataWindow,

    DataWindowChild,

    DataStore

    A column name is used as a field name in a FIELD buffer. Only modified rows are used as data.

    SingleLineEdit,

    MultiLineEdit

    A Control.Tag name is used as a field name in a FIELD buffer. Control.Text is used as data.

    StaticText, EditMask

    A Control.Tag name is used as a field name in a FIELD buffer. Control.Text is used as data.

    ListBox

    A Control.Tag name is used as a field name in a FIELD buffer. All selected items are used as data.

    DropDownListBox

    A Control.Tag name is used as a field name in a FIELD buffer. Only a selected item is used as data.

    CheckBox

    A Control.Tag name is used as a field name in a FIELD buffer. Only selected items are used as data.

    RadioButton

    A Control.Tag name is used as a field name in a FIELD buffer. Only a selected item is used as data.

    Objects that can be used as output are the same as those that can be used as input. Data must be added in ListBox and DropDownListBox objects. The following describes uo_tmax’s instance variables.

    Variable Description

    Append

    If set to TRUE, when DataWindow is specified in output, existing data in DataWindow will not be removed and only added. (Default value: FALSE)

    DelBuf

    If set to TRUE, when DataWindow is specified in input, data will be drawn from DeleteBuffer and PrimaryBuffer of DataWindow. (Default value: TRUE)

    DataOnFail

    If set to TRUE, data will be displayed on a screen even though a service failed. (Default value: FALSE)

    AppData

    Data that is automatically added whenever a service is called is specified in the input type of pb_tpcall().

    DateFmt, TimeFmt,

    DateTimeFmt

    Format referred to when a Date/Time/DateTime column value is converted to a String value.

    Since pb_tpcallw calls pb_tpcall internally, refer to variables used in pb_tpcall().

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Example

    long ret
windowobject indata[], outdata[]

indata[1] = dw_1
indata[2] = sle_input
outdata[1] = dw_2
uo_tmax.flags = 0;

ret = uo_tmax.pb_tpcallw ("SVC1", indata, outdata)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    pb_tpcall(), tuxcall()

2.18. pb_tpcancel

Cancels a descriptor returned by pb_tpacall(), which means that a result from a called service will not be received. If it is tried to cancel a descriptor for a global transaction, an error will occur. If the pb_tpcancel() call succeeds, cd will no longer be used and the transaction cannot be committed and can only be rolled back.

  • Prototype

    pb_tpcancel ( integer cd )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by pb_tpacall().

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Error

    For detailed information about error codes, refer to tpcancel in Tmax Reference Guide.

  • Example

    string input, itype, form[], output[]
int length, cd, ret

length = len(before.text)

itype = "STRUCT~tkstrdata~n"
input = string(length) + "~t" + before.text + "~n"
form[1] = "len~n" + "sdata~n" + "~n"
form[2] = "~n"
output[1] = space(1024)

cd = uo_tmax.pb_tpacall("SYNC", itype, input)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tpcancel(cd)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    pb_tpacall(), pb_tpgetrply()

2.19. pb_tpcommit

Commits a transaction.

  • Prototype

    pb_tpcommit ()
returns integer

  • Return value

    Return value Description

    0

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tx_commit in Tmax Reference Guide.

  • Example

    ...
if _is_tx <> true then
...
end if

ret = uo_tmax.pb_tpcommit()
if ret < 0 then
   error processing
   ...
end If

_is_tx = false
...

  • Related functions

    pb_tx_begin(), pb_tx_rollback(), pb_tpbegin()

2.20. pb_tpconnect

Connects to an interactive service. Connected servers and clients send and receive data each other by using pb_tpsend() and pb_tprecv().

  • Prototype

    pb_tpconnect ( string svcname, string itype, string idata, long arg_flag )
returns integer

  • Parameter

    Parameter Description

    svcname

    Name of an interactive service to be called.

    itype

    Format of string data in a buffer. Strings are deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    idata

    Format of string data in a buffer that will save data to be processed. Input data is deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    arg_flag

    The following flags can be used in pb_tpconnect().

    • TPNOTRAN

      If a pb_tpconnect() caller requests a service with this flags in transaction mode, the service is excluded from transaction mode and executed.

      If a service does not support a transaction in transaction mode, flags must be set to TPNOTRAN when pb_tpconnect() is called in transaction mode. Even when flags is set to TPNOTRAN, transaction timeout has influence on the service. Even if a service called with TPNOTRAN fails, this will not affect a caller’s transaction.

    • TPSENDONLY

      After a connection is made, a function caller can only send data and only a requested service can be executed. A function caller has a communication control at first. Either TPSENDONLY or TPRECVONLY must be specified.

    • TPRECVONLY

      After a connection is made, a function caller can only receive data and a requested service starts sending data. A requested service has a communication control at first. Either TPSENDONLY or TPRECVONLY must be specified.

    • TPNOTIME

      A function caller ignores blocking timeout and continuously waits for a response. However, if pb_tpconnect() is called in transaction timeout, blocking timeout applies to the function.

    • TPSIGSTRT

      Used to allow a signal interrupt. If calling a system function is interrupted due to an internal signal interrupt, the system function will be called again. If a signal interrupt occurs without TPSIGSTRT, the function will fail and tperrno will be set to TPGOTSIG.

  • Return value

    Return value Description

    Descriptor (cd greater than or equal to 1)

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Error

    For detailed information about error codes, refer to tpconnect in Tmax Reference Guide.

  • Example

    int ret, cd
string itype, otype, idata, form[], odata[]

itype = "STRING~t~n"
otype = "STRING~t~n"
idata = string(len(before.text)) + "~t" + before.text + "~n"
odata[1] = space(1024)

cd = uo_tmax.pb_tpconnect("CONV", itype, idata, uo_tmax.TPRECVONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tprecv(cd, form, odata, uo_tmax.TPFLAGS)
if ret < 0 then
   if uo_tmax.revent <> uo_tmax.TPEV_SENDONLY or &
      uo_tmax.revent = uo_tmax.TPEV_SVCSUCC then
         error processing
         ...
   end if
   ...
end if

  • Related functions

    pb_tpsend(), tp_tprecv(), pb_tpdiscon()

2.21. pb_tpconv

Sends and receives messages to and from an interactive service specified with the 1st parameter. pb_tpconv() uses a FIELD buffer among buffers supported by Tmax.

  • Prototype

    pb_tpconv ( long cd, string itype, string idata, ref string form[],
            ref string odata[], long arg_flag )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by tp_connect().

    itype

    Format of string data in a buffer. Strings are deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    • STRUCT buffer type

      itype = "STRUCT~tstruct_name~n"

    • STRING buffer type

      itype ="STRING~t~n"

    • FIELD KEY buffer type

      itype = "FIELD~t~n"

    idata

    Format of string data that includes a service name. Input data is delimited by a tab character ("~t") and a line is ended with a newline character ("~n").

    form

    Has the format of result odata. Field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    arg_flag

    All flags values that can be used in pb_tpsend() and pb_tprecv() are available.

  • Example

    int ret, cd
string idata, itype
itype = "FIELD~t~n"
input = "INPUT~t" + sle_1.text + "~n"

form[1] = "OUTPUT~n~n"
form[2] = "~n"
output[1] = space(1024)

cd = uo_tmax.tp_connect(idata, uo_tmax.TPRECVONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tpconv(cd, itype, idata, form, output, uo_tmax.TPNOFLAGS)
if ret < 0 then
   if uo_tmax.revent <> uo_tmax.TPEV_SENDONLY or &
      uo_tmax.revent = uo_tmax.TPEV_SVCSUCC then
         error processing
         ...
   end if
   ...
end if
...

2.22. pb_tpdiscon

Forcibly ends a connection for communication and causes the TPEV_DISCONIMM event. This function can be called only by an interactive communication starter.

  • Prototype

    pb_tpdiscon ( integer cd )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by pb_tpconnect().

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tpdiscon in Tmax Reference Guide.

  • Example

    int ret, cd
string itype, otype, idata, form[], odata[]

itype = "STRING~t~n"
otype = "STRING~t~n"
idata = string(len(before.text)) + "~t" + before.text + "~n"
odata[1] = space(1024)

cd = uo_tmax.pb_tpconnect("CONV", itype, idata, uo_tmax.TPSENDONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tpdiscon(cd)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    pb_tpconnect(), tp_tpsend(), pb_tprecv()

2.23. pb_tpend

Ends a connection to a Tmax system.

  • Prototype

    pb_tpend()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tpend in Tmax Reference Guide.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax
...
ret = uo_tmax.pb_tpend()
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    tp_term()

2.24. pb_tpfcall

Extended function of pb_tpcall(). pb_tpfcall() can receive input data from a file and save result data to a file. The function saves result data of a field specified with form to odata and result data of a field specified with fform to a file named fodata. pb_tpfcall() uses a FIELD buffer among buffers supported by Tmax.

  • Prototype

    pb_tpfcall ( string svcname, string itype, string idata, string form[],
             ref string odata[], string ifilename, string fform[],
             ref string fodata[] )
returns integer

  • Parameter

    Parameter Description

    svcname

    Name of a service to be called.

    itype

    Buffer type. Strings are delimited by a tab character ("~t") and a line is ended with a newline character ("~n").

    idata

    Buffer that will save data to be processed. Strings are delimited by a tab character ("~t") and a line is ended with a newline character ("~n").

    form

    Has the format of a service result, odata. For a STRUCT buffer, odata consists of members of a used structure, and for a FIELD KEY buffer, it consists of names of used fields. Members or field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    ifilename

    Name of a file that includes input data. In the file, a field name and data are separated by a tab character ("~t") and a data part is ended with a newline character ("~n").

    (E.g., FIELD_NAME1+ "~t" + VALUE1+ "~n" + & FIELD_NAME2+ "~t" VALUE2 "~n" + & "~n")

    fform

    Has the format of a service result, fodata. For a STRUCT buffer, odata consists of members of a used structure, and for a FIELD KEY buffer, it consists of names of used fields. Members or field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    fodata

    Name of a file to which a result will be saved.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Example

    ...
InputFile ="c:\temp\fdata0.txt"
InputFile = FileOpen(InputFile, StreamMode!, Write!, LockReadWrite!, Replace!)
...
uo_tmax.f_fdata(dw_input, InputFile)

if FileClose(InputFile) <> 1 then
   error processing
   ...
end if
...
ret = uo_tmax.pb_tpfcall("FCALL", itype, input, form, output,
                          inputfilename, fform, foutput)
if ret = -1 then
   error processing
   ...
end if
...

  • Related functions

    f_fdata

2.25. pb_tpfree

Frees buffers that were allocated by using pb_tpalloc().

tpfree() removes information related to a buffer before freeing the buffer. If the function call succeeded, buf cannot be passed as a parameter to an XATMI routine and no longer be used.

  • Prototype

    pb_tpfree ( long buf )

  • Parameter

    Parameter Description

    buf

    Address of a buffer that was allocated by using pb_tpalloc(). If buf is NULL, nothing is processed. To free some types of buffers, relevant data or status information must be removed.

  • Return value

    None.

  • Example

    long ret
long buf

u_tmax uo_tmax
uo_tmax = CREATE u_tmax
...
ret = uo_tmax.pb_tpstart()
if ret < 0 then
   error processing
   ...
end if
...
buf = uo_tmax.pb_tpalloc("CARRAY", "", 40000)
if buf = 0 then
   error process
   ...
end if
...
pb_tpfree(buf)

  • Related functions

    pb_tpalloc()

2.26. pb_tpget

Reads data corresponding to an address specified in the 1st parameter to a buffer specified in the 2nd parameter as much size as a value specified in the 3rd parameter.

Since there is no char * address in PowerBuilder, a long address is sent to <pb.dll> and <pb.dll> sends string data corresponding to the address to a buffer specified in the 2nd parameter.

  • Prototype

    pb_tpget ( long buf, ref string loc, long size )
returns long

  • Parameter

    Parameter Description

    buf

    Address of data to be read in the long format.

    loc

    Buffer to which data sent from <pb.dll> will be saved.

    size

    Size of data to be read.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    tperrno is set to one of the following values.

    Error Code Description

    TPEINVAL

    An argument is invalid. rcvbuf is NULL, or mid is less than 0.

    TPEITYPE

    The size of memory secured by PowerBuilder is smaller than that of data to be received.

    TPEOTYPE

    Received data does not exist or is invalid.

    TPEMATCH

    No data corresponds to a given mid.

  • Example

    ret_string = Space(20)
ll_ret = uo_tmax.pb_tpget(buf, ret_string, 20)

  • Related functions

    pb_tpput()

2.27. pb_tpgetrply

Receives a reply to a request sent from pb_tpacall(). Blocking communication is made by default. Once a function is called, it waits until it receives a reply or blocking timeout occurs. If the timeout occurs, the call will be failed and tperrno will be set to TPETIME.

  • Prototype

    pb_tpgetrply ( integer cd, ref string form[], ref string odata[] )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor retruned by pb_tpacall(). This descriptor allows to identify a reply to a request.

    form

    Has the format of a service result, odata. For a STRUCT buffer, odata consists of members of a used structure, and for a FIELD KEY buffer, it consists of names of used fields. Members or field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Error

    For detailed information about error codes, refer to tpgetrply in Tmax Reference Guide.

  • Example

    string input, itype, form[], output[]
int length, cd, ret

length = len(before.text)

itype = "STRUCT~tkstrdata~n"
input = string(length) + "~t" + before.text + "~n"
form[1] = "len~n" + "sdata~n" + "~n"
form[2] = "~n"
output[1] = space(1024)

cd = uo_tmax.pb_tpacall("SYNC", itype, input)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tpgetrply(cd, form, output)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    f_form(), pb_tpacall(), pb_tpcancel(), pb_tpcall()

2.28. pb_tpgetunsol

Processes unrequested messages received. Note that pb_tpgetunsol() can be blocked unlike pb_tpsetunsol(). For more information this function, refer to tpgetunsol in Tmax Reference Guide.

  • Prototype

    pb_tpgetunsol ( integer types, string form[], ref string odata[],
                integer arg_flags )
returns integer

  • Parameter

    Parameter Description

    types

    Type (either 'TPBROADCAST' or 'TPSENDTOCLI') of a method of receiving unrequested messages.

    form

    Form of unrequested data received.

    odata

    Buffer to which unrequested data received will be saved.

    arg_flag

    Option to handle blocking. Either one of the following values can be set.

    • TPBLOCK: After a function is called, the function waits until a message is received in blocked state.

    • TPNOTIME: Even after a function is called, the function is not blocked. If no message is received, the next routine will be processed.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    tperrno is set to one of the following values.

    Error Code Description

    TPEINVAL

    An argument is invalid. rcvbuf is NULL, or mid is less than 0.

    TPEITYPE

    The size of memory secured by PowerBuilder is smaller than that of data to be received.

    TPEOTYPE

    Received data does not exist or is invalid.

    TPEMATCH

    No data corresponds to a given mid.

  • Example

    string form[], tmp[]
...
tmp[1] = space(30)

ret = uo_tmax.pb_tpgetunsol(uo_tmax.TPBROADCAST, form[], tmp[],
                            uo_tmax.TPBLOCK)
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpsetunsol(), pb_getunsold()

2.29. pb_tpput

Saves data specified in the 2nd parameter to a location with an address specified in the 1st parameter as much size as a value specified in the 3rd parameter.

  • Prototype

    pb_tpput ( long buf, any value, long size )
returns long

  • Parameter

    Parameter Description

    buf

    Address of data to be saved in the long format.

    loc

    Data to be saved.

    size

    Size of data to be saved.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    tperrno is set to one of the following values.

    Error Code Description

    TPEINVAL

    An argument is invalid. rcvbuf is NULL, or mid is less than 0.

    TPEITYPE

    The size of memory secured by PowerBuilder is smaller than that of data to be received.

    TPEOTYPE

    Received data does not exist or is invalid.

    TPEMATCH

    No data corresponds to a given mid.

  • Example

    blob  lb_tmp
bytes_read = FileRead(li_FileNum, lb_tmp)
ll_ret = uo_tmax.pb_tpput(buf, lb_tmp, bytes_read)

  • Related functions

    pb_tpget()

2.30. pb_tprecv

Receives data in interactive communication. A function caller must not have a communication control.

  • Prototype

    pb_tprecv ( integer cd, ref string form[], ref string odata[], long arg_flag )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by pb_tpconnect().

    form

    Has the format of a service result, odata. For a STRUCT buffer, odata consists of members of a used structure, and for a FIELD KEY buffer, it consists of names of used fields. Members or field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    arg_flag

    The following flags can be used in pb_tprecv().

    • TPNOBLOCK

      A function caller does not wait until data is received. Received data is returned if any. If this flag is not set and there is no received data, a function caller waits until data is received.

    • TPNOTIME

      A function caller ignores blocking timeout and waits until a response is received. However, pb_tprecv() is called within transaction timeout, blocking timeout applies.

    • TPSIGRSTRT

      Signal interrupts are allowed. If a system function call is interrupted by a signal interrupt, the function is called again. If a signal interrupt occurs without this flag, a function call will fail and tperrno will be set to TPGOTSIG.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed.

    A return value is -1 in the following two cases; an error an event occurred. Therefore, when -1 is returned, it needs to be checked whether an error or an event occurred. If an error occurs, tperrno will be set to an error code that is not PB_TPEEVENT. If an event occurs, tperrno will be set to PB_TPEEVENT (number 22) and revent will be set to one the following values.

    Value Description

    TPEV_DISCONIMM

    (Number 1)

    A communication starter forcibly ends a connection by using pb_tpdiscon(), or a connection is ended due to a communication error, etc.

    TPEV_SVCERR

    (Number 2)

    A service is ended abnormally.

    TPEV_SVCFAIL

    (Number 4)

    A service calls tpreturn() with TPFAIL.

    TPEV_SVCSUCC

    (Number 8)

    A service calls tpreturn() with TPSUCCESS (normal end).

    TPEV_SENDONLY

    (Number 32)

    A connected program gives up a communication control. A recipient that receives TPEV_SENDONLY can send data but cannot receive any data until the recipient receives a control.

    PB_TPEV_SVCSUCC, PB_TPEV_SVCFAIL

    A user code sent by a service is saved in tpurcoode.

  • Error

    For detailed information about error codes, refer to tprecv in Tmax Reference Guide.

  • Example

    int ret, cd
string itype, otype, idata, form[], odata[]

itype = "STRING~t~n"
otype = "STRING~t~n"
idata = string(len(before.text)) + "~t" + before.text + "~n"
odata[1] = space(1024)

cd = uo_tmax.pb_tpconnect("CONV", itype, idata, uo_tmax.TPSENDONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tprecv(cd, form, odata, uo_tmax.TPNOFLAGS)
if ret < 0 then
   if uo_tmax.revent <> uo_tmax.TPEV_SENDONLY or &
      uo_tmax.revent = uo_tmax.TPEV_SVCSUCC then
         error processing
         ...
   end if
   ...
end if

  • Related functions

    pb_tpconnect(), tp_tprecv(), pb_tpdiscon()

2.31. pb_tpreset

Immediately ends a currently established connection. If the TPESYSTEM error occurs, reconnect to a Tmax system because the TPESYSTEM error in a client module is mostly due to a network error. Use pb_tpreset() to end a currently established connection and then request a service again or reconnect to the Tmax system.

  • Prototype

    pb_tpreset ()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to Tmax Reference Guide.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax

uo_tmax.usr_name = 'tmaxclient'
uo_tmax.clt_name = 'cilent01'
uo_tmax.dom_pwd = 'tmax'
uo_tmax.usr_pwd = 'client01'
uo_tmax.flags = uo_tmax.TPUNSOL_IGN
...
ret = uo_tmax.pb_tpstart()
if ret < 0 then
   error processing
   ...
end if
...

ret = uo_tmax.pb_tpreset()
if ret < 0 then
   error processing
   ...
endif

2.32. pb_tpsend

Sends data in interactive communication. A function caller must have a communication control.

  • Prototype

    pb_tpsend ( integer cd, string itype, string idata, long arg_flag )
returns integer

  • Parameter

    Parameter Description

    svcname

    Descriptor returned by pb_tpconnect().

    itype

    Buffer type. Strings are deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    idata

    Buffer that will save data to be processed. Strings are deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    arg_flag

    The following flags can be used in pb_tpsend().

    • TPRECVONLY

      A function caller sends data and then gives a communication control to the other program. Therefore, the function caller cannot call pb_tpsend() until it receives the communication control again. The other program receives data through pb_tprecv() along with the TPEV_SENDONLY event that means a communication control. The other program cannot call pb_tprecv() until it sends the communication control.

      Data and events are not sent in blocking state (for example, when an internal buffer is full of messages to be sent). If pb_tpsend() is called without this flag, a function caller waits until timeout (either transaction or blocking timeout) occurs or blocking state is released.

    • TPNOBLOCK

      Data and events are not sent in blocking state (for example, when an internal buffer is full of messages to be sent). If pb_tpsend() is called without this flag, a function caller waits until timeout (either transaction or blocking timeout) occurs or blocking state is released.

    • TPNOTIME

      A function caller ignores blocking timeout and waits until a response is received. However, pb_tpconnect() is called within transaction timeout, the transaction timeout applies.

    • TPSIGSTRT

      Signal interrupts are allowed. If a system function call is interrupted by a signal interrupt, the function is called again. If a signal interrupt occurs without this flag, a function call will fail and tperrno will be set to TPGOTSIG.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed.

    A return value is -1 in the following two cases; an error or an event occurred. Therefore, when -1 is returned, it needs to be checked whether an error or an event occurred. If an error occurs, tperrno will be set to an error code that is not PB_TPEEVENT. If an event occurs, tperrno will be set to PB_TPEEVENT (number 22) and revent will be set to one the following values.

    Value Description

    TPEV_DISCONIMM

    (Number 1)

    A communication starter forcibly ends a connection by using pb_tpdiscon(), or a connection is ended due to a communication error, etc.

    TPEV_SVCFAIL

    (Number 4)

    A service calls tpreturn() with TPFAIL.

    TPEV_SVCERR

    (Number 2)

    A service is ended abnormally.

    PB_TPEV_SVCSUCC, PB_TPEV_SVCFAIL

    A user code sent by a service is saved in tpurcoode.

  • Error

    For detailed information about error codes, refer to tpsend in Tmax Reference Guide.

  • Example

    int ret, cd
string itype, otype, idata, form[], odata[]

itype = "STRING~t~n"
otype = "STRING~t~n"
idata = string(len(before.text)) + "~t" + before.text + "~n"
odata[1] = space(1024)

cd = uo_tmax.pb_tpconnect("CONV", itype, idata, uo_tmax.TPSENDONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tpsend(cd, itype, idata, uo_tmax.TPRECVONLY)
if ret < 0 then
   error processing
   ...
endif

  • Related functions

    pb_tpconnect(), tp_tprecv(), pb_tpdiscon()

2.33. pb_tpset_timeout

Changes blocking timeout (service timeout) that is set in a server. If service timeout is set, a reply to a service request is awaited for a period of time set in arg_timeout. If a reply is not received until arg_timeout is reached, the timeout error will occur and the service will fail.

Timeout changed by pb_tpset_timeout() applies to a service request that is sent after the function is called. The timeout is valid until pb_tpset_timeout() is called again or a client or server process is terminated.

  • Prototype

    pb_tpset_timeout ( integer arg_timeout )
returns integer

  • Parameter

    Parameter Description

    arg_timeout

    Maximum time for waiting for a reply to a service request.

    (Unit: seconds)

  • Return value

    Return value Description

    0

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to timeout in Tmax Reference Guide.

  • Example

    long ret
long buf
u_tmax uo_tmax
uo_tmax = CREATE u_tmax
uo_tmax.usr_name = 'tmaxclient'
uo_tmax.clt_name = 'cilent01'
uo_tmax.dom_pwd = 'tmax'
uo_tmax.usr_pwd = 'client01'
uo_tmax.flags = uo_tmax.TPUNSOL_IGN
...
ret = uo_tmax.pb_tpstart()
if ret < 0 then
   error processing
   ...
end if
...
buf = uo_tmax.pb_tpalloc("CARRAY", "", 40000)
...
ret = uo_tmax.pb_tpset_timeout(5)
if ret < 0 then
   error processing
   ...
end if
...
ret = uo_tmax.pb_tpcall("SYNC", itype, input, form, output)

2.34. pb_tpsetunsol

Enables to receive unrequested messages. Messages are received by using pb_getunsold(). To receive unrequested messages by using pb_tpsetunsol() and pb_getunsold(), flags, an instance variable of u_tmax, must be set to TPUNSOL_HND and then pb_tpstart() must be called.

  • Prototype

    pb_tpsetunsol (unsignedinteger hwnd, string ename, unsignedinteger mid,
               long arg_flags)
returns integer

  • Parameter

    Parameter Description

    hwnd

    Window handle.

    ename

    Event name. This name is available only when tppost is used. This name must be identical with a service name to receive data.

    mid

    Message identifier used to search for a relevant message.

    arg_flags

    Unrequested message type:

    • TPBROADCAST

    • TPSENDTOCLI

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    tperrno is set to one of the following values.

    Error Code Description

    TPEINVAL

    An argument is invalid. (e.g., The length of an event name exceeds the maximum value (16).)

  • Example

    ...
uo_tmax.flags = uo_tmax.TPUNSOL_HND
...
ret = uo_tmax.pb_tpsetunsol ( HANDLE(this), "", 1025, uo_tmax.TPBROADCAST )
if ret = -1 then
   error processing
   ...
end if
...
unsoldata = space(1024)
ret = uo_tmax.pb_getunsold(unsoldata, rlen, 1025)
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_getunsold()

2.35. pb_tpstart

Connect to Tmax. Before pb_tpstart() is called, the following environment variables used to connect to Tmax must be specified: an IP address of a server to be connected (TMAX_ HOST_ADDR) and a port number of the server (TMAX_HOST_PORT). To use a structure, the path of SDLFILE must be registered with an environment variable. To use a FIELD (FDL) buffer, the path of FDLFILE must be registered with an environment variable.

The following describes how to environment variables.

  • In DOS

    Use <autoexec.bat>.

    SET TMAX_HOST_ADDR=192.168.0.1              Server IP address
SET TMAX_HOST_PORT=8888                     Server port number
SET SDLFILE=C:\tmax\sdl\tmax.sdl            To use the structure type
SET FDLFILE=C:\tmax\fdl\tmax.fdl            To use the FIELD type

  • In UNIX(Korn Shell)

    Use <.profile>.

    export TMAX_HOST_ADDR=192.168.0.1           Server IP address
export TMAX_HOST_PORT=8888                  Server port number
export SDLFILE=C:\tmax\sdl\tmax.sdl         To use the structure type
export FDLFILE=C:\tmax\fdl\tmax.fdl         To use the FIELD type

The following describes pb_tpstart().

  • Prototype

    pb_tpstart()
returns integer

  • Instance variables of u_tmax

    Variable Description

    usr_name

    User connection identifier.

    clt_name

    Client connection identifier.

    dom_pwd

    Domain connection password.

    usr_pwd

    User connection password.

    flags

    Option to receive unrequested messages.

    • TPUNSOL_IGN: ignore unrequested messages.

    • TPUNSOL_POLL: receive unrequested messages (by using pb_tpgetunsol()).

    • TPUNSOL_HND: receive unrequested messages.

  • Return value

    Return value Description

    0 or 1

    Function call succeeded.

    • 0: A connection is established to a primary host.

    • 1: A connection is established to a backup host.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tpstart in Tmax Reference Guide.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax
uo_tmax.usr_name = 'tmaxclient'
uo_tmax.clt_name = 'cilent01'
uo_tmax.dom_pwd = 'tmax'
uo_tmax.usr_pwd = 'client01'
uo_tmax.flags = uo_tmax.TPUNSOL_IGN
...
ret = uo_tmax.pb_tpstart()
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tmaxreadenv(), tp_init()

2.36. pb_tptobackup

Connects to a backup system. pb_tpstart() tries to automatically connect to a backup system when a Tmax server to which a client tries to connect is in abnormal state. pb_tptobackup() is used to intentionally connect to a backup system first.

Since pb_tptobackup() does not receive TPSTART_T with a parameter, it cannot connect to a system that needs security. If security-related items are configured in a configuration file, the relevant backup system cannot be accessed. To use pb_tptobackup(), TMAX_BACKUP_ADDR and TMAX_BACKUP_PORT must be registered in a system configuration file (e.g., <.profile> in KornShell).

  • Prototype

    pb_tptobackup ()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tptobackup in Tmax Reference Guide.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax

...
ret = uo_tmax.pb_tptobackup()
if ret < 0 then
   error processing
   ...
end if
...

2.37. pb_tx_begin

Begins a global transaction. A function caller becomes in transaction mode. Once a transaction starts, the function caller must call pb_tx_commit() or pb_tx_rollback() to complete the transaction.

  • Prototype

    pb_tx_begin ()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tx_begin in Tmax Reference Guide.

  • Example

    ...
if _is_tx <> true then
   ret = uo_tmax.pb_tx_begin()
   if ret < 0 then
      error processing
      ...
   end if
   _is_tx = true
end If
...

  • Related functions

    pb_tx_commit(), pb_tx_rollback()

2.38. pb_tx_commit

Commits a transaction.

  • Prototype

    pb_tx_commit ()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tx_commit in Tmax Reference Guide.

  • Example

    ...
if _is_tx <> true then
...
end if

ret = uo_tmax.pb_tx_commit()
if ret < 0 then
   error processing
   ...
end If

_is_tx = false
...

  • Related functions

    pb_tx_begin(), pb_tx_rollback()

2.39. pb_tx_rollback

Rolls back a transaction.

  • Prototype

    pb_tx_rollback ()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tx_rollback in Tmax Reference Guide.

  • Example

    ...
ret = uo_tmax.pb_tpcall("INSERT", itype, input, form[], output[])
if ret < 0 then
   if _is_tx = true then
   ret = uo_tmax.pb_tx_rollback()
       if ret < 0 then
          error processing
          ...
        end if
        _is_tx = false
   end if
   error processing
   ...
end if
...

  • Related functions

    pb_tx_begin(), pb_tx_commit(), pb_tx_info()

2.40. pb_tx_set_commit_return

Determines the time to commit a global transaction by using a parameter (w_return).

  • Prototype

    pb_tx_set_commit_return ( long w_return )
returns integer

  • Parameter

    Parameter Description

    w_return

    One of the following values:

    • TX_COMMIT_DECISION_LOGGED: commit a transaction after the 1st phase of the 2PC (two-phase commit) protocol is finished by using pb_tx_commit(). A result can be obtained rapidly, but the result might be an unexpected value.

    • TX_COMMIT_COMPLETED: commit a transaction after the 2PC (two-phase commit) protocol is completely processed by using pb_tx_commit().

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tx_set_commit_return in Tmax Reference Guide.

  • Example

    ...
if ret = uo_tmax.pb_tx_set_commit_return(uo_tmax.TX_COMMIT_COMPLETED)
   if ret < 0 then
       error processing
       ...
   end if

if _is_tx <> true then
   ret = uo_tmax.pb_tx_begin()
   if ret < 0 then
      error processing
      ...
   end if
   _is_tx = true
end If
...

  • Related functions

    pb_tx_info()

2.41. pb_tx_set_transaction_control

Determines whether to start a new transaction by using a parameter (control) before pb_tx_commit() or pb_tx_rollback() is returned. The initial value of "control" is TX_UNCHAINED.

  • Prototype

    pb_tx_set_transaction_control ( long control )
returns integer

  • Parameter

    Parameter Description

    control

    One of the following values.

    • TX_UNCHAINED: do not start a new transaction. A new transaction can be started only by using pb_tx_begin().

    • TX_CHAINED: automatically start a new transaction after pb_tx_commit() or pb_tx_rollback() is called.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tx_set_transaction_control in Tmax Reference Guide.

  • Example

    ...
if ret = uo_tmax.pb_tx_set_transaction_control(uo_tmax.TX_CHAINED)
   if ret < 0 then
      error processing
      ...
   end if

if _is_tx <> true then
   ret = uo_tmax.pb_tx_begin()
   if ret < 0 then
      error processing
      ...
   end if
   _is_tx = true
end If
...

  • Related functions

    pb_tx_info()

2.42. pb_tx_set_transaction_timeout

Sets transaction timeout.

  • Prototype

    pb_tx_set_transaction_timeout ( long timeout )
returns integer

  • Parameter

    Parameter Description

    timeout

    Maximum time for a transaction.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tx_set_transaction_timeout in Tmax Reference Guide.

  • Example

    ...
if ret = uo_tmax.pb_tx_set_transaction_timeout(5)
   if ret < 0 then
      error processing
      ...
   end if

if _is_tx <> true then
   ret = uo_tmax.pb_tx_begin()
   if ret < 0 then
      error processing
      ...
   end if
   _is_tx = true
end If
...

  • Related functions

    pb_tx_info()

2.43. pb_uotmax_ver

Queries the version of tmax.pbd.

  • Prototype

    pb_uotmax_ver ()
returns string

  • Return value

    The tmax.pbd version

2.44. pb_tx_info

Queries information about global transactions. Information about transaction xid is set in u_tmax’s data, when_return, transaction_control, transaction_timeout, and transaction_stat.

  • Prototype

    pb_tx_info ()
returns integer

  • Return value

    Return value Description

    1

    The function is called in transaction mode. If a return value is 1, the following Tmax instance variable is set.

    • data: Current transaction ID in the format of "machine number:CLH number:branch number".

    • when_return: Current commit_return value. This can be modified by pb_tx_set_commit_return().

    • transaction_control: Current transaction control value. This can be modified by pb_tx_set_transaction_control().

    • transaction_timeout: Current transaction’s timeout. This can be modified by pb_tx_set_transaction_timeout().

    • transaction_stat: Current transaction state.

    -1

    Function call failed. The error code is set in tperrno.

  • Error

    For detailed information about error codes, refer to tx_info in Tmax Reference Guide.

  • Example

    ...
if _is_tx <> true then
   ret = uo_tmax.pb_tx_begin()
   if ret < 0 then
      error processing
      ...
   end if
   _is_tx = true
end If
if ret = uo_tmax.pb_tx_info()
   if ret < 0 then
      error processing
      ...
   end if
   ...
end if

  • Related functions

    pb_tx_begin(), pb_tx_commit(), pb_tx_rollback()

2.45. tp_abort

Aborts a transaction.

  • Prototype

    tp_abort ( long arg_flags )
returns integer

  • Parameter

    Parameter Description

    arg_flags

    Currently not used. Although a user passes any argument, an error does not occur.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    ...
ret = uo_tmax.pb_tpcall("INSERT", itype, input, form[], output[])
if ret < 0 then
   if _is_tx = true then
      ret = uo_tmax.tp_abort(0)
      if ret < 0 then
         error processing
         ...
      end if
      _is_tx = false
   end if
   error processing
   ...
end if
...

  • Related functions

    tp_begin(), tp_commit()

2.46. tp_acall

Asynchronously calls a service and then returns a descriptor to be used to receive a reply (refer to tp_getrply) without waiting for a reply. tp_acall() can be used to call multiple services at the same time and receive their results or to process another task while waiting for a reply.

tp_acall() uses FIELD buffers.

  • Prototype

    tp_acall ( ref string idata )
returns integer

  • Parameter

    Parameter Description

    idata

    Data string including a service name. Input data is separated by a tab character ("~t") and a line is ended with a newline character ("~n").

  • Return value

    Return value Description

    cd greater than or equal to 1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    string input, form[], odata[]
int cd, ret
...

input = "SRVCNM" + "~t" + "TOUPPER" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"

form[1] = "OUTPUT~n~n"
form[2] = "~n"
output[1] = space(1024)

cd = uo_tmax.tp_acall(input)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.tp_getrply(cd, form, output)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    pb_tpacall(), tp_getrply()

2.47. tp_begin

Begins a global transaction. A function caller becomes in transaction mode. Once a transaction starts, the function caller must call tp_commit() or tp_abort() to complete the transaction.

  • Prototype

    tp_begin ( unsignedlong timeout, long arg_flags )
returns integer

  • Parameter

    Parameter Description

    timeout

    Maximum time for completing a transaction. If a transaction is not completed within this period of time, the timeout error will occur and the transaction will be stopped. (Unit: seconds)

    arg_flags

    Currently not used.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    ...
if _is_tx <> true then
   ret = uo_tmax.tp_begin(10, 0)
   if ret < 0 then
      error processing
      ...
   end if
   _is_tx = true
end If
...

  • Related functions

    tp_commit(), tp_abort()

2.48. tp_broadcast

Sends a message to a specified client.

  • Prototype

    tp_broadcast ( string nodename, string usrname, string cltname, string idata )
returns integer

  • Parameter

    Parameter Description

    nodename

    Name of a node that includes a client to which a message will be sent.

    usrname

    Name of a user to which a message will be sent. This name must be identical with usr_name used in pb_tpstart().

    cltname

    Name of a client to which a message will be sent. This name must be identical with clt_name used in pb_tpstart().

    idata

    Data string including a service name. Input data is separated by a tab character ("~t") and a line is ended with a newline character ("~n").

    nodename, usrname, and cltname parameters are logical names used to select a target client. username and cltname can contain a wildcard character such as a question mark (?) and an asterisk (*). nodename can be an asterisk. NULL can also be used like a wildcard, which means all clients are targets.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    string nodename, usrname, cltname, data
int ret
...
nodename = "tmax"
usrname = "*"
cltname = "*"
data = "SRVCNM" + "~t" + "BROAD" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"~n"
ret = uo_tmax.tp_broadcast(nodename, usrname, cltname, data)
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpbroadcast()

2.49. tp_call

Synchronously calls a Tmax service by using idata and saves a returned result of column data in the form format to odata. tp_call() uses FIELD (FDL) buffers among buffers supported by Tmax.

  • Prototype

    tp_call ( string idata, string form[], ref string odata[] )
returns integer

  • Parameter

    Parameter Description

    idata

    Data string including a service name. Input data is separated by a tab character ("~t") and a line is ended with a newline character ("~n").

    form

    Has the format of a service result, odata. Field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    The following describes Tmax’s instance variables. The flags and timeout variables are set before a service is called, and the other variables are set after a service is called.

    Variable Description

    msg

    Message sent from a service program.

    tperrno

    Buffer in which an error code will be saved if an error occurs.

    tpurcode

    Buffer in which a user code (the 2nd argument of tpreturn()) sent from a server will be saved.

    flags

    The following flags can be used in pb_tpcall().

    • TPNOTRAN: used to call a service in non transaction mode.

    • TPNOCHANGE: guarantee that types of a buffer for initial allocation and a buffer for responses are identical.

    • TPNOBLOCK: used to call a service in non blocking mode.

    • TPNOTIME: ignore blocking timeout.

    [Note]

    tuxedo_compat(true) operates according to flags. For more information, refer to tuxedo_compat().

    timeout

    Blocking timeout used in pb_tx_set_transaction_timeout().

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Example

    ...
input = "SRVCNM" + "~t" + "TOUPPER" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"

form[1] = "OUTPUT~n~n"
form[2] = "~n"
output[1] = space(1024)

ret = uo_tmax. tp_call(input, form, output)
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpcall(), f_data(), f_datadel(), f_form(), tuxcall()

2.50. tp_cancel

Cancels a descriptor returned by tp_acall(), which means that a result from a called service will not be received. The transaction cannot be committed and can only be rolled back.

  • Prototype

    tp_cancel ( integer cd )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by tp_acall().

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    string input, form[], odata[]
int cd, ret
...
input = "SRVCNM" + "~t" + "TOUPPER" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"
form[1] = "OUTPUT~n~n"
form[2] = "~n"
output[1] = space(1024)

cd = uo_tmax.tp_acall(input)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.pb_tpcancel(cd)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    tp_acall(), tp_getrply()

2.51. tp_commit

Commits a transaction.

  • Prototype

    tp_commit ( long arg_flags )
returns integer

  • Parameter

    Parameter Description

    arg_flags

    Currently not used.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    ...
if _is_tx <> true then
...
end if

ret = uo_tmax.tp_commit(0)
if ret < 0 then
   error processing
   ...
end If

_is_tx = false
...

  • Related functions

    tp_begin(), tp_abort()

2.52. tp_connect

Connects to an interactive service. Connected servers and clients send and receive data each other by using tp_send() and tp_recv(). tp_connect() uses FIELD buffers.

  • Prototype

    tp_connect ( string idata, long arg_flag )
returns integer

  • Parameter

    Parameter Description

    idata

    String data including a service name. Input data is deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    arg_flag

    The following flags can be used in tp_connect().

    • TPNOTRAN

      If a pb_tpconnect() caller requests a service with this flags in transaction mode, the service is excluded from transaction mode and executed.

      If a service does not support a transaction in transaction mode, flags must be set to TPNOTRAN when pb_tpconnect() is called in transaction mode. Even when flags is set to TPNOTRAN, transaction timeout has influence on the service. Even if a service called with TPNOTRAN fails, this will not affect a caller’s transaction.

    • TPSENDONLY

      After a connection is made, a function caller can only send data and only a requested service can be executed. A function caller has a communication control at first. Either TPSENDONLY or TPRECVONLY must be specified.

    • TPRECVONLY

      After a connection is made, a function caller can only receive data and a requested service starts sending data. A requested service has a communication control at first. Either TPSENDONLY or TPRECVONLY must be specified.

    • TPNOTIME

      A function caller ignores blocking timeout and continuously waits for a response. However, if pb_tpconnect() is called in transaction timeout, blocking timeout applies to the function.

    • TPSIGSTRT

      Used to allow a signal interrupt. If calling a system function is interrupted due to an internal signal interrupt, the system function will be called again. If a signal interrupt occurs without TPSIGSTRT, the function will fail and tperrno will be set to TPGOTSIG.

  • Return value

    Return value Description

    Descriptor

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    int ret, cd
string idata

idata = "SRVCNM" + "~t" + "CONV" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"

cd = uo_tmax.tp_connect(idata, uo_tmax.TPRECVONLY)
if cd < 0 then
   error processing
   ...
end if
...

  • Related functions

    tp_send(), tp_recv(), tp_conv(), tp_discon()

2.53. tp_conv

Sends and receives messages to and from an interactive service specified with cd. tp_conv() uses a FIELD buffer among buffers supported by Tmax.

  • Prototype

    tp_conv ( integer cd, string idata, ref string form[], ref string odata[],
          long arg_flag )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by tp_connect().

    idata

    Format of string data in a buffer. Strings are deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    form

    Has the format of a service result, odata. Field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    arg_flag

    All

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed.

    A return value is -1 in the following two cases; an error occurred or an event occurred. Therefore, when -1 is returned, it needs to be checked whether an error or an event occurred. If an error occurs, tperrno will be set to an error code that is not PB_TPEEVENT. If an event occurs, tperrno will be set to PB_TPEEVENT (number 22) and revent will be set to one the following values.

    Value Description

    TPEV_DISCONIMM

    (Number 1)

    A communication starter forcibly ends a connection by using pb_tpdiscon(), or a connection is ended due to a communication error, etc.

    TPEV_SVCERR

    (Number 2)

    A service is ended abnormally.

    TPEV_SVCFAIL

    (Number 4)

    A service calls tpreturn() with TPFAIL.

    TPEV_SENDONLY

    (Number 32)

    A connected program gives up a communication control. A recipient that receives TPEV_SENDONLY can send data but cannot receive any data until the recipient receives a control.

    PB_TPEV_SVCSUCC, PB_TPEV_SVCFAIL

    A user code sent by a service is saved in tpurcoode.

  • Error

    For detailed information about error codes, refer to tpacall in Tmax Reference Guide.

  • Example

    int ret, cd
string idata

idata = "SRVCNM" + "~t" + "CONV" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"
form[1] = "OUTPUT~n~n"
form[2] = "~n"
output[1] = space(1024)

cd = uo_tmax.tp_connect(idata, uo_tmax.TPRECVONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.tp_conv(cd, idata, form, output, uo_tmax.TPNOFLAGS)
if ret < 0 then
   if uo_tmax.revent <> uo_tmax.TPEV_SENDONLY or &
      uo_tmax.revent = uo_tmax.TPEV_SVCSUCC then
         error processing
         ...
   end if
   ...
end if
...

  • Related functions

    tp_connect(), tp_discon(), tp_send(), tp_recv()

2.54. tp_discon

Forcibly ends a connection for communication and causes the TPEV_DISCONIMM event.

A normal method for ending an interactive service is executing tpreturn() in the service. tp_discon() is used when a client needs to immediately end a connection to an interactive service. If the function is called, data sent after this function call will be lost and the transaction can only be stopped.

  • Prototype

    tp_discon ( integer cd )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by tp_connect().

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    int ret, cd
string idata

idata = "SRVCNM" + "~t" + "CONV" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"

cd = uo_tmax.tp_connect(idata, uo_tmax.TPRECVONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.tp_discon(cd)
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpconnect(), tp_tpsend(), pb_tprecv()

2.55. tp_fcall

Synchronously calls a Tmax service. tp_fcall() can receive input data from not only memory but also a file and save result data to memory and a file at the same time.

tp_fcall() uses FIELD(FDL) buffer among buffers supported by Tmax. This function saves result data of a field specified with form to odata and result data of a field specified with fform to a file named foutdata.

  • Prototype

    tp_fcall ( string idata, string form[], ref string odata[], string ifilename,
           string fform[], ref string foutdata[] )
returns integer

  • Parameter

    Parameter Description

    idata

    Data string including a service name. Input data is separated by a tab character ("~t") and a line is ended with a newline character ("~n").

    form

    Has the format of a service result, odata. Field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    ifilename

    Name of a file that includes input data. In the file, a field name and data are separated by a tab character ("~t") and a data part is ended with a newline character ("~n").

    fform

    Has the format of a service result, foutdata. Field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    foutdata

    Name of a file to which a result will be saved.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Example

    ...
InputFile ="c:\temp\fdata0.txt"
InputFile = FileOpen(InputFile, StreamMode!, Write!, LockReadWrite!, Replace!)
...
uo_tmax.f_fdata(dw_input, InputFile)

if FileClose(InputFile) <> 1 then
   error processing
   ...
end if
...
ret = uo_tmax.tp_fcall(input, form, output, inputfilename, fform, foutput)
if ret = -1 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpfcall(), f_data(), f_datadel(), f_form()

2.56. tp_getrply

Receives data in asynchronous communication. tp_getrply() is used to receive a reply to a request sent by tp_acall(). This function uses FIELD buffer among buffers supported by Tmax. form and odata (the 2nd and 3rd parameters) are the same as those in tp_call().

  • Prototype

    tp_getrply ( integer cd, ref string form[], ref string odata[] )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by tp_acall(). This descriptor allows to identify a reply to a request.

    form

    Has the format of a service result, odata. Field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Example

    string input, form[], odata[]
int cd, ret
...
input = "SRVCNM" + "~t" + "TOUPPER" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"
form[1] = "OUTPUT~n~n"
form[2] = "~n"
output[1] = space(1024)

cd = uo_tmax.tp_acall(input)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.tp_getrply(cd, form, output)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    pb_tpgetrply(), tp_acall()

2.57. tp_init

Connect to Tmax. To use tp_init(), environment variables must be set as in pb_tpstart().

  • Prototype

    tp_init ()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax

uo_tmax.usr_name = 'tmaxclient'
uo_tmax.clt_name = 'cilent01'
uo_tmax.dom_pwd = 'tmax'
uo_tmax.usr_pwd = 'client01'
uo_tmax.flags = uo_tmax.TPUNSOL_IGN
...
ret = uo_tmax.tp_initt()
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    pb_tpstart()

2.58. tp_recv

Receives data in interactive communication. A function caller must not have a communication control. tp_recv() uses FIELD buffer among buffers supported by Tmax.

  • Prototype

    tp_recv ( integer cd, ref string form[], ref string odata[], long arg_flag )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by pb_tpconnect().

    form

    Has the format of a service result, odata. Field names are delimited by a newline character ("~n") and a newline character ("~n") is added at the end to specify the end of Form. To specify the final end of a Form array, a Form that consists of a newline character is added.

    odata

    Buffer that will save a result. Data is delimited by a tab character ("~t") in order to save data in DataWindow by using the ImportString function of PowerBuilder and rows are delimited by a newline character ("~n").

    arg_flag

    The following flags can be used in tp_recv().

    • TPNOBLOCK

      A function caller does not wait until data is received. Received data is returned if any. If this flag is not set and there is no received data, a function caller waits until data is received.

    • TPNOTIME

      A function caller ignores blocking timeout and waits until a response is received. However, pb_tprecv() is called within transaction timeout, blocking timeout applies.

    • TPSIGRSTRT

      Signal interrupts are allowed. If a system function call is interrupted by a signal interrupt, the function is called again. If a signal interrupt occurs without this flag, a function call will fail and tperrno will be set to TPGOTSIG.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed.

    A return value is -1 in the following two cases; an error occurred or an event occurred. Therefore, when -1 is returned, it needs to be checked whether an error or an event occurred. If an error occurs, tperrno will be set to an error code that is not PB_TPEEVENT. If an event occurs, tperrno will be set to PB_TPEEVENT (number 22) and revent will be set to one the following values.

    Value Description

    TPEV_DISCONIMM

    (Number 1)

    A communication starter forcibly ends a connection by using pb_tpdiscon(), or a connection is ended due to a communication error, etc.

    TPEV_SVCERR

    (Number 2)

    A service is ended abnormally.

    TPEV_SVCFAIL

    (Number 4)

    A service calls tpreturn() with TPFAIL.

    TPEV_SVCSUCC

    (Number 8)

    A service calls tpreturn() with TPSUCCESS (normal end).

    TPEV_SENDONLY

    (Number 32)

    A connected program gives up a communication control. A recipient that receives TPEV_SENDONLY can send data but cannot receive any data until the recipient receives a control.

    PB_TPEV_SVCSUCC, PB_TPEV_SVCFAIL

    A user code sent by a service is saved in tpurcoode.

  • Example

    int ret, cd
string itype, otype, idata, form[], odata[]

idata = "SRVCNM" + "~t" + "CONV" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"

cd = uo_tmax.tp_connect(idata, uo_tmax.TPRECVONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.tp_recv(cd, form, odata, uo_tmax.TPNOFLAGS)
if ret < 0 then
   if uo_tmax.revent <> uo_tmax.TPEV_SENDONLY or &
      uo_tmax.revent = uo_tmax.TPEV_SVCSUCC then
         error processing
         ...
   end if
   ...
end if

  • Related functions

    tp_connect(), tp_discon(), tp_send(), tp_conv()

2.59. tp_send

Sends data in interactive communication. A function caller must have a communication control. tp_send() uses FIELD buffer among buffers supported by Tmax.

  • Prototype

    tp_send ( integer cd, string idata, long arg_flag )
returns integer

  • Parameter

    Parameter Description

    cd

    Descriptor returned by pb_tpconnect().

    idata

    Format of string data that includes a service name. Input data is deliminated by a tab character ("~t") and a line is ended with a newline character ("~n").

    arg_flag

    The following flags can be used in tp_send()

    • TPRECVONLY

      A function caller sends data and then gives a communication control to the other program. Therefore, the function caller cannot call pb_tpsend() until it receives the communication control again. The other program receives data through pb_tprecv() along with the TPEV_SENDONLY event that means a communication control. The other program cannot call pb_tprecv() until it sends the communication control.

    • TPNOBLOCK

      Data and events are not sent in blocking state (for example, when an internal buffer is full of messages to be sent). If pb_tpsend() is called without this flag, a function caller waits until timeout (either transaction or blocking timeout) occurs or blocking state is released.

    • TPNOTIME

      A function caller ignores blocking timeout and waits until a response is received. However, pb_tpconnect() is called within transaction timeout, the transaction timeout applies.

    • TPSIGSTRT

      Signal interrupts are allowed. If a system function call is interrupted by a signal interrupt, the function is called again. If a signal interrupt occurs without this flag, a function call will fail and tperrno will be set to TPGOTSIG.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed.

    A return value is -1 in the following two cases; an error occurred or an event occurred. Therefore, when -1 is returned, it needs to be checked whether an error or an event occurred. If an error occurs, tperrno will be set to an error code that is not PB_TPEEVENT. If an event occurs, tperrno will be set to PB_TPEEVENT (number 22) and revent will be set to one the following values.

    Value Description

    TPEV_DISCONIMM

    (Number 1)

    A communication starter forcibly ends a connection by using pb_tpdiscon(), or a connection is ended due to a communication error, etc.

    TPEV_SVCERR

    (Number 2)

    A service is ended abnormally.

    TPEV_SVCFAIL

    (Number 4)

    A service calls tpreturn() with TPFAIL.

  • Example

    int ret, cd
string itype, otype, idata, form[], odata[]

idata = "SRVCNM" + "~t" + "CONV" + "~n" + &
"FIELD_NAME1" + "~t" + "VALUE1" + "~n" + &
"FIELD_NAME2" + "~t" + "VALUE2" + "~n" + &
"~n"

cd = uo_tmax.tp_connect(idata, uo_tmax.TPSENDONLY)
if cd < 0 then
   error processing
   ...
end if

ret = uo_tmax.tp_send(idata, uo_tmax.TPRECVONLY)
if ret < 0 then
   error processing
   ...
end if
...

  • Related functions

    tp_connect(), tp_discon(), tp_recv(), tp_conv()

2.60. tp_subscribe

Receives messages that are transferred from a server through tppost(). If a message with a name specified in event_name is sent through tppost(), a window event specified in message_id will occur in a window specified in hwnd. When a message is received, the message’s ID is sent to Message.WordParm in a window event handling routine of a corresponding window. A message ID identifies each messages in get_evtname() or get_data(). To turn off the configuration of receiving the messages, use tp_unsubscribe().

  • Prototype

    tp_subscribe (unsignedinteger hwnd, string event_name,
              unsignedinteger message_id)
returns integer

  • Parameter

    Parameter Description

    hwnd

    Window handle.

    event_name

    Event name.

    message_id

    Message ID.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Related functions

    tp_unsubscribe()

2.61. tp_term

Ends a connection to a Tmax system.

  • Prototype

    tp_term ()
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax

...

ret = uo_tmax.tp_term()
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    pb_tpend()

2.62. tp_unsubscrib

Turns off the configuration set with tp_subscribe() or tp_setunsol() to receive messages from a window (hwnd).

  • Prototype

    tp_unsubscribe ( unsignedinteger hwnd )
returns integer

  • Parameter

    Parameter Description

    hwnd

    Window handle.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Related functions

    tp_subscribe()

2.63. tpbegin

Processes functions of both pb_tx_set_transaction_timeout() and pb_tx_begin(). Since pb_tpbegin() has the same prototype as in Tuxedo, applications developed for Tuxedo can be used without any modifications.

  • Prototype

    pb_tpbegin ( unsignedlong arg_timeout )
returns integer

  • Parameter

    Parameter Description

    arg_timeout

    Maximum time for a transaction, which is the same as the timeout parameter of pb_tx_set_transaction_timeout().

  • Return value

    Refer to pb_tx_set_transaction_timeout and pb_tx_begin.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax

uo_tmax.usr_name = 'tmaxclient'
uo_tmax.clt_name = 'cilent01'
uo_tmax.dom_pwd = 'tmax'
uo_tmax.usr_pwd = 'client01'
uo_tmax.flags = uo_tmax.TPUNSOL_IGN
...
ret = uo_tmax.pb_tpstart()
if ret < 0 then
   error processing
   ...
end if
...
ret = uo_tmax.pb_tpbegin(7)

  • Related functions

    pb_tx_set_transaction_timeout(), pb_tx_begin()

2.64. tuxcall

Synchronously calls a Tmax service. tuxcall() calls a service by using PowerObject specified in the sobject parameter and then saves its result PowerObject specified in the robject parameter. tuxcall() FIELD buffers among buffers supported by Tmax.

Object Description

DataWindow,

DataWindowChild,

DataStore

A column name is used as a FIELD buffer field name. Only modified rows are used as data.

SingleLineEdit,

MultiLineEdit

A Control.Tag name is used as a FIELD buffer field name. Control.Text is used as data.

taticText, EditMasks

A Control.Tag name is used as a FIELD buffer field name. Control.Text is used as data.

ListBox

A Control.Tag name is used as a FIELD buffer field name. All selected items are used as data.

DropDownListBox

A Control.Tag name is used as a FIELD buffer field name. Only selected items are used as data.

CheckBox

A Control.Tag name is used as a FIELD buffer field name. Only selected item is used as data.

RadioButton

A Control.Tag name is used as a FIELD buffer field name. Only selected item is used as data.

Objects that can be specified in robject are the same as objects that can be used as input. For ListBox and DropDownListBox, data needs to be added.

The following describes u_tmax’s instance variables.

Variable Description

dwAppend

If this variable is TRUE and robject is DataWindow, existing data in the DataWindow will be not removed and data will only be added to the DataWindow. (Default value: FALSE)

dwDelBuf

If this variable is TRUE and sobject is DataWindow, data will be removed from DeleteBuffer and PrimaryBuffer of the DataWindow. (Default value: TRUE)

DataOnFail

If this variable is TRUE, data will be displayed on the screen even though a service failed. (Default value: FALSE)

AuxData

Specifies data that is added automatically whenever a service is called as an input of tp_call().

DateFmt, TimeFmt, DateTimeFmt

Specifies a format that is referenced when a Date/Time/DateTime column value is converted into a string.

Since tuxcall() uses tp_call() internally, refer to variables used in tp_call() as well as the previous variables.

  • Prototype

    tuxcall ( string svcname, powerobject sobject[], ref powerobject robject[] )
returns integer

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno, and the error message is saved in msg.

  • Example

    long ret
windowobject indata[], outdata[]
indata[1] = dw_1
indata[2] = sle_input
outdata[1] = dw_2
uo_tmax.flags = 0;

ret = uo_tmax.tuxcall("SVC1", indata, outdata)
if ret < 0 then
   error processing
   ...
end if

  • Related functions

    tp_call(), pb_tpcallw()

2.65. tuxedo_compat

Provides compatibility with Tuxedo libraries for some APIs. The operation is the same as when the PB_TUXCOMPAT environment variable is 'Y'. If tuxedo_compat() is used, the following will change.

  • isBlocked()

    If the TPNOBLOCK flags is set, tasks can be processed while a service is requested (e.g., a tp_call() call). Whether a service request is being processed can be checked through isBlocked().

  • msg variables

    If a value is set in the STATLIN field in return data of a service, the value is set in a msg instance variable. If a service call fails and no value is set in the STATLIN field, tpstrerror(tperrno) will be set in msg.

  • tp_fcall(), tp_fcall32()

    Even though filename is not entered, the TPEINVAL error will not occur.

  • API operation

    tuxcall(), tuxfcall32(), tp_call(), tp_call32(), tp_fcall(), tp_fcall32(), and pb_etpcall() APIs operates according to a flags value.

    flags Description

    TPNOTRAN

    tx_begin() and tx_commit() are not called internally. If this flags is not set, tx_begin() and tx_commit() will be called whenever an API is called.

    TPNOBLOCK

    tpacall() is used internally. yield() is called whenever tpgetrply() is called.

    While a service request is processed, another task can be processed because a user interface is not blocked. tpusleep() is internally called every 1000 ms until a reply is received and then yield() is called. To change the period of calling tpusleep(), modify the value of the tuxedo_noblock_usleep instance variable in microseconds.

The following describes tuxedo_compat().

  • Prototype

    tuxedo_compat(boolean sw)
returns boolean

  • Parameter

    Parameter Description

    sw

    If set to true, compatibility with Tuxedo libraries for some APIs will be provided.

  • Return value

    Return value Description

    true

    Function call succeeded.

    false

    Function call failed.

  • Example

    boolean ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax
...
ret = uo_tmax.tuxreadenv("tmax.env", "TMAX")
if ret = false then
   error processing
end if

ret = uo_tmax.tuxedo_compat(true)
if ret = false then
   error processing
end if

uo_tmax.tuxedo_noblock_usleep = 500

  • Related functions

    pb_tmaxreadenv(), tuxcall(), tuxfcall32(), tp_call(), tp_call32(), tp_fcall(), tp_fcall32(), pb_etpcall(), isBlocked()

2.66. tuxreadenv

Reads information about a system to connect from a file and configures environment variables by using the information. This function must be called before trying to connect to a Tmax system because it configures environment variables used to connect the Tmax system. By referring to the environment variables, a Tmax system can be connected through pb_tpstart() or tp_init().

A configuration file in which environment variables are defined is different according to OS. csh and ksh are defined in <.cshrc> and <.profile> respectively in UNIX, and they are defined in <autoexec.bat> in DOS. If it needs to connect to multiple systems, a client can change a system to connect. Since multiple systems cannot be configured only with environment variables, the environment variables must be registered in a file and then the file must be used.

  • Prototype

    tuxreadenv ( string env_file, string section )
returns integer

  • Parameter

    Parameter Description

    env_file

    Name of a file that contains information about a system to be connected. The file must be text, and included information must be set in a valid format.

    section

    Identifier for information registered in a configuration file. This allows to identify each system when multiple systems are configured.

  • Return value

    Return value Description

    1

    Function call succeeded.

    -1

    Function call failed. The error code is set in tperrno.

  • Example

    long ret
u_tmax uo_tmax
uo_tmax = CREATE u_tmax
...
ret = uo_tmax.tuxreadenv("./tmax.env", "TMAX")
if ret < 0 then
   error processing
end if

  • Related functions

    pb_tmaxreadenv()

3. Example Program

The following describes an example program that queries, modifies, deletes, and adds names, positions, managers in charge, joining dates, salaries, contracted periods, and departments with a key of an employee number. Filed key buffers are used in the program.

3.1. Program Organization

Each program consists of the following files.

  • Common program

    File Description

    demo.f

    Defines field key buffers.

    tmconfig.m

    Tmax configuration file.

  • Client program

    File Description

    demo.pbl

    Client program.

  • Server program

    File Description

    emp_c.pc

    Server program that provides services (Oracle source).

    emp_c.mk

    Makefile.

3.2. Program Description

The following describes each program.

  • Client program

    Item Description

    User object connection

    tmax.pbd is linked to applications.

    Buffer

    'fdl' files need to be created by compiling FIELD KEY buffers and field key files with the fdlc utility.

    Communication

    Synchronous communication is made by using pb_tpcall().

    Transaction

    Transactions for queries, modifications, deletions, and additions are handled.

    Tmax connection

    A connection is established whenever a service operates and ended after the service completes.

  • Server program

    Item Description

    Service

    FDLSELECT, FDLUPDATE, FDLDELETE, and FDLINSERT are written.

    Database

    Oracle database is used. Database information is specified in SVRGROUP of a system configuration file.

3.3. Common Program

Database EMP Table

The following is an example table that used for DB operations.

EMPNO        NUMBER        NOT NULL        P1
ENAME        VARCHAR(16)
JOB          VARCHAR(16)
MGR          NUMBER
HIREDATE     DATE
SAL          NUMBER(7,2)
COMM         NUMBER(7,2)
DEPTNO       NUMBER
Field Key Buffer Definition

The following is an example file that defines a field key buffer.

<demo.f>

#For tmax demo employee program
EMPNO    7500    long        -         -
ENAME    7501    string      -         -
JOB      7502    string      -         -
MGR      7503    long        -         -
DATE     7504    string      -         -
SAL      7505    float       -         -
COMM     7506    float       -         -
DEPTNO   7507    long        -         -
E_TYPE   9009    long        -         -
E_CODE   9010    long        -         -
E_MSG    9011    string      -         -
E_TMP    9012    long        -         -
Tmax Configuration

The following is an example Tmax configuration file.

<tmconfig.m>

*DOMAIN
dom1        SHMKEY = 70000,
            MAXUSER = 200,
            MINCLH = 1,
            MAXCLH = 5,
            TPORTNO = 8888,
            BLOCKTIME = 200,
            TXTIME = 200

*NODE
tmax1       TMAXDIR = "/home/tmax",
            APPDIR = "/home/tmax/appbin",
            PATHDIR = "/home/tmax/path",
            TLOGDIR = "/home/tmax/log/tlog",
            SLOGDIR = "/home/tmax/log/slog"
            ULOGDIR = "/home/tmax/log/ulog"

*SVRGROUP
svg1        NODENAME = tmax1,
            DBNAME = ORACLE,
            OPENINFO = "ORACLE_XA+Acc=P/scott/tiger+SesTm=60",
            TMSNAME = svg1_tms

*SERVER
emp_c       SVGNAME = svg1, MIN = 1

*SERVICE
FDLSELECT   SVRNAME = emp_c
FDLUPDATE   SVRNAME = emp_c
FDLDELETE   SVRNAME = emp_c
FDLINSERT   SVRNAME = emp_c

3.4. Client Program

The following is an initial screen that consists of 1 data window, 8 single-line editors, and 5 buttons.

image

The following describes each button.

  • Search

    Click the [Search] button after entering 'Employee Number' to display data with the entered employee number ±50 in DataWindow. Search Button Script is an example script that implements the execution of the [Search] button.

    The following shows an example result.

    image

    Click the [Back] button to move to the initial screen. Back Button Script is an example script that implements the execution of the [Back] button.

  • Modification

    Click the [Modify] button after entering 'Employee Number' and new data to replace existing data with the new data. Modify Button Script is an example script that implements the execution of the [Modify] button.

  • Deletion

    Click the [Delete] button after entering 'Employee Number' to delete the corresponding data. Delete Button Script is an example script that implements the execution of the [Delete] button.

  • Addition

    Click the [Add] button after entering all data for an employee to add the employee. Add Button Script is an example script that implements the execution of the [Add] button.

  • Exit

    Click the [Exit] button to exit the program. Exit Button Script is an example script that implements the execution of the [Exit] button.

Global Variables
u_tmax                uo_tmax
boolean               btxRun, bConnect
Window Function
＊tmaxconnect ()
returns Boolean
IF uo_tmax.pb_tpstart()<0 THEN
   st_err.text = ("Cannot connect to a server.\n tpstart() Failed: Error Code ="
                   + string(uo_tmax.tperrno))
   return FALSE
END IF
return TRUE

＊inputcheck ( integer  inputnum ) returns Boolean
IF isnull( sle_empno.text ) OR sle_empno.text = "" THEN
   st_err.text = "An employee number must be entered."
   return FALSE
END IF

IF( inputnum = 1) THEN
return TRUE

IF isnull( sle_name.text ) OR sle_name.text = "" THEN
   goto errormsg
IF isnull( sle_job.text ) OR sle_job.text = ""   THEN
   goto errormsg
IF isnull( sle_mgr.text ) OR sle_mgr.text = ""   THEN
   goto errormsg
IF (len(sle_date.text) <>8 )                     THEN
   goto errormsg
IF isnull( sle_sal.text ) OR sle_sal.text = ""   THEN
   goto errormsg
IF isnull( sle_comm.text ) OR sle_comm.text = "" THEN
   goto errormsg
IF isnull( sle_dept.text ) OR sle_dept.text = "" THEN
   goto errormsg
return TRUE

errormsg:
   st_err.text = "All items must be entered. A joining date must be entered in the format of YYYYMMDD."
return FALSE

＊clearwindow () returns Booleansle_empno.clear()
sle_name.clear()
sle_job.clear()
sle_mgr.clear()
sle_date.clear()
sle_sal.clear()
sle_comm.clear()
sle_dept.clear()
sle_empno.setfocus()

＊errorprocess ( string infomsg )
st_err.text = InfoMsg
IF( btxRun = TRUE ) THEN
    uo_tmax.pb_tx_rollback()
    btxRun = FALSE
END IF

IF( bconnect = TRUE ) THEN
    uo_tmax.pb_tpend()
    bconnect = FALSE
END IF

＊successprocess ( string infomsg )
st_err.text = InfoMsg

IF( btxRun = TRUE ) THEN
    uo_tmax.pb_tx_commit()
    btxRun = FALSE
END IF

IF( bconnect = TRUE ) THEN
    uo_tmax.pb_tpend()
    bconnect = FALSE
END IF
Open Script
string FileName

uo_tmax = CREATE u_tmax
uo_tmax.flags = 0

FileName ="D:\PB\MyProgram\tmax.env"
IF uo_tmax.pb_tmaxreadenv( FileName, "tmax1") <0 THEN
   messagebox( "Eviroment Error","Enviroment File Loading Failed : Error Code ="
                + string(uo_tmax.tperrno))
   return
END IF
open(w_demo)

The following is an example script that implements the execution of the [Search] button.

string itype, idata, form[], odata[]

IF(inputcheck(1) = FALSE) THEN return

itype = "FIELD~t~n"
idata = "EMPNO"+"~t"+sle_empno.text+"~n"
form[1] ="EMPNO~n" + &
         "ENAME~n" + &
         "JOB~n" + &
         "MGR~n" + &
         "DATE~n" + &
         "SAL~n" + &
         "COMM~n" + &
         "DEPTNO~n" + &
         "E_TYPE~nE_CODE~nE_MSG~nE_TMP~n~n"
form[2] = "~n"//"E_TYPE~nE_CODE~nE_MSG~nE_TMP~n~n"
odata[1] = space(1024)

bConnect = tmaxconnect()
IF bConnect = FALSE THEN
   errorprocess( "Cannot connect to a server.")
   return
END IF

IF uo_tmax.pb_tpcall("FDLSELECT", itype, idata, form[], odata[]) <0 THEN
   errorprocess( uo_tmax.f_getdata(form[1], odata[1], 1, "E_MSG") )
   return
END IF

dw_out.importstring(odata[1])
dw_out.visible  = TRUE
cb_back.visible = TRUE
cb_sel.enabled  = FALSE
cb_udt.enabled  = FALSE
cb_del.enabled  = FALSE
cb_ins.enabled  = FALSE
cb_exit.enabled = FALSE
successprocess( sle_empno.text + "information has been found.")
Modify Button Script

The following is an example script that implements the execution of the [Modify] button.

string itype, idata, form[], odata[]

IF(inputcheck(0) = FALSE) THEN return

itype = "FIELD~t~n"
idata = "EMPNO~t" + sle_empno.text+"~n" + &
                    "ENAME~t"+sle_name.text+"~n" + &
                    "JOB~t"+sle_job.text+"~n" + &
                    "MGR~t"+sle_mgr.text+"~n" + &
                    "DATE~t" +sle_date.text+"~n" + &
                    "SAL~t" +sle_sal.text+"~n" + &
                    "COMM~t" +sle_comm.text+"~n" + &
                    "DEPTNO~t" +sle_dept.text+"~n~n"
form[1] = "E_TYPE~nE_CODE~nE_MSG~nE_TMP~n~n"
form[2] = "~n"
odata[1] = space(1024)

bConnect = tmaxconnect()
IF bConnect = FALSE THEN
   errorprocess( "Cannot connect to a server.")
   return
END IF

IF btxrun = FALSE THEN
   IF uo_tmax.pb_tx_begin()<0 THEN
      errorprocess( "pb_tx_begin Error")
      return
    END IF
    btxrun = TRUE
END IF

IF uo_tmax.pb_tpcall("FDLUPDATE", itype, idata, form[], odata[])<0 THEN
   errorprocess( "Error:\n"+uo_tmax.f_getdata(form[1], odata[1], 1, "E_MSG") )
   return
END IF

clearwindow()
successprocess( sle_empno.text + "information has been modified." )
Delete Button Script

The following is an example script that implements the execution of the [Delete] button.

int ret
string itype, idata, form[], odata[]

IF(inputcheck(1) = FALSE) THEN return

itype = "FIELD~t~n"
idata = "EMPNO"+"~t"+sle_empno.text+"~n~n"
form[1] = "E_TYPE~nE_CODE~nE_MSG~nE_TMP~n~n"
form[2] = "~n"
odata[1] = space(1024);

bConnect = tmaxconnect()
IF bConnect = FALSE THEN
   errorprocess( "Cannot connect to a server.")
   return
END IF

IF btxrun = FALSE THEN
   IF uo_tmax.pb_tx_begin()<0 THEN
      errorprocess( "pb_tx_begin Error")
      return
   END IF
   btxrun = TRUE
END IF

IF uo_tmax.pb_tpcall("FDLDELETE", itype, idata, form[], odata[])<0 THEN
   errorprocess( uo_tmax.f_getdata(form[1], odata[1], 1, "E_MSG") )
   return
END IF

successprocess( sle_empno.text + "information has been modified." )
clearwindow()
Add Button Script

The following is an example script that implements the execution of the [Add] button.

long ret
string itype, idata, form[], odata[]

IF(inputcheck(0) = FALSE) THEN return

itype = "FIELD~t~n"
idata = "EMPNO~t"+sle_empno.text+"~n" + &
        "ENAME~t"+sle_name.text+"~n" + &
        "JOB~t"+sle_job.text+"~n" + &
        "MGR~t"+sle_mgr.text+"~n" + &
        "DATE~t"+sle_date.text+"~n" + &
        "SAL~t"+sle_sal.text+"~n" + &
        "COMM~t"+sle_comm.text+"~n" + &
        "DEPTNO~t"+sle_dept.text+"~n" + &
        "~n"
form[1] = "E_TYPE~nE_CODE~nE_MSG~nE_TMP~n~n"
form[2] = "~n"
odata[1] = space(1024);

bConnect = tmaxconnect()
IF bConnect = FALSE THEN
   errorprocess( "Cannot connect to a server.")
   return
END IF

IF btxrun = FALSE THEN
   IF uo_tmax.pb_tx_begin()<0 THEN
      errorprocess( "pb_tx_begin Error")
      return
   END IF
   btxrun = TRUE
END IF

IF uo_tmax.pb_tpcall("FDLINSERT", itype, idata, form[], odata[])<0 THEN
   errorprocess( uo_tmax.f_getdata(form[1], odata[1], 1, "E_MSG") )
   return
END IF

successprocess( sle_empno.text + "information has been modified." )
clearwindow()
Exit Button Script

The following is an example script that implements the execution of the [Exit] button.

close(w_demo)
Back Button Script

The following is an example script that implements the execution of the [Back] button.

int i
cb_sel.enabled  = TRUE
cb_udt.enabled  = TRUE
cb_del.enabled  = TRUE
cb_ins.enabled  = TRUE
cb_exit.enabled = TRUE

FOR i=1 to (dw_out.rowcount()+2)
    dw_out.deleterow ( 1 )
NEXT

clearwindow()
dw_out.visible = FALSE
cb_back.visible = FALSE

3.5. Server Program

Service Program

The following is an example service program.

#include <stdio.h>
#include <ctype.h>
#include <tuxinc/macro.h>
#include "../../fdl/demo_fdl.h"

EXEC SQL include sqlca.h;
EXEC SQL INCLUDE ORACA;
EXEC ORACLE  OPTION (ORACA=YES);
EXEC ORACLE  OPTION (RELEASE_CURSOR=YES);

#define INP   1
#define ORA   2
#define TMX   3
#define APP   4

EXEC SQL begin declare section;
int  h_empno;
char h_ename[11];
char h_job[10];
int  h_mgr;
char h_date[11];
float h_sal;
float h_comm;
int  h_deptno;
EXEC SQL end declare section;

void svc_error(long type, long err_code, char *msg, long tmp);

FDLINSERT( TPSVCINFO *msg )
{
        FBUF *rcvbuf;
        int i, occurrence;
        rcvbuf = (FBUF *)msg->data;
        h_empno = h_mgr = h_sal = h_comm = h_deptno = 0;

        memset( h_ename, 0x00, sizeof( h_ename ) );
        memset( h_job, 0x00, sizeof( h_job ) );
        memset( h_date, 0x00, sizeof( h_date ) );

        occurrence = fbkeyoccur(rcvbuf, EMPNO);

        for (i=0; i< occurrence; i++){
                fbget_tu ( rcvbuf, EMPNO, i, (char *)&h_empno, 0 );
                fbget_tu ( rcvbuf, MGR,   i, (char *)&h_mgr, 0 );
                fbget_tu ( rcvbuf, SAL,   i, (char *)&h_sal, 0 );
                fbget_tu ( rcvbuf, COMM,  i, (char *)&h_comm, 0 );
                fbget_tu ( rcvbuf, DEPTNO,i, (char *)&h_deptno, 0 );
                fbget_tu ( rcvbuf, ENAME, i, (char *)h_ename, 0 );
                fbget_tu ( rcvbuf, JOB  , i, (char *)h_job, 0 );
                fbget_tu ( rcvbuf, DATE , i, (char *)h_date, 0 );

                EXEC SQL INSERT
                INTO emp( empno, ename, job, mgr, hiredate, sal,comm, deptno)
                VALUES ( :h_empno, :h_ename, :h_job, :h_mgr,
                to_date(:h_date,'yyyymmdd'), :h_sal, :h_comm, :h_deptno );
        }

        if(sqlca.sqlcode != 0)
             goto LB_DBERROR;

        EXEC SQL WHENEVER SQLERROR
             goto LB_DBERROR;

        tpreturn(TPSUCCESS, 0L, (char *)rcvbuf, 0L, 0L);

        LB_DBERROR :
             EXEC SQL WHENEVER SQLERROR CONTINUE;
             svc_error(ORA, sqlca.sqlcode, sqlca.sqlerrm.sqlerrmc, 0);
}


FDLDELETE( TPSVCINFO *msg )
{
        FBUF *rcvbuf;
        int i, occurrence;

        rcvbuf = ( FBUF *)msg->data;
        occurrence = fbkeyoccur(rcvbuf, EMPNO);

        for (i=0; i< occurrence; i++){
             fbget_tu (rcvbuf, EMPNO, i, (char *)&h_empno , 0);

             EXEC SQL DELETE
                  FROM emp
                  WHERE empno = :h_empno;
        }
        if(sqlca.sqlcode != 0)
             goto LB_DBERROR;

        EXEC SQL WHENEVER SQLERROR
             goto LB_DBERROR ;

        EXEC SQL WHENEVER NOT FOUND
             goto LB_DBERROR ;

        tpreturn(TPSUCCESS, 0L, (char *)rcvbuf, 0L, 0L);

        LB_DBERROR :
             EXEC SQL WHENEVER SQLERROR CONTINUE;
             svc_error(ORA, sqlca.sqlcode, sqlca.sqlerrm.sqlerrmc, 0);
}

FDLSELECT( TPSVCINFO *msg )
{
        FBUF *rcvbuf;
        FLDLEN fldlen;
        int i=0, ROWMEM=200, CHKROW=500;

        rcvbuf = (FBUF *)msg->data;

        if((rcvbuf=(FBUF *)tprealloc((char *)rcvbuf,ROWMEM*CHKROW))==NULL){
            rcvbuf=(FBUF *)msg->data;
            goto LB_TMAXERROR ;
        }

        h_empno = h_mgr = h_sal = h_comm = h_deptno = 0;

        memset( h_ename, 0x00, sizeof( h_ename ) );
        memset( h_job, 0x00, sizeof( h_job ) );
        memset( h_date, 0x00, sizeof( h_date ) );

        fbget_tu( rcvbuf, EMPNO, 0, (char *)&h_empno, &fldlen);

        EXEC SQL DECLARE DB_CUR CURSOR FOR
        SELECT  nvl(empno,0), nvl(ename,' '), nvl(job,' '),
                nvl(to_char(hiredate,'yyyymmdd'),' '),  nvl(mgr,0),
                nvl(sal,0), nvl(comm,0), nvl(deptno,0)
        FROM  emp
        WHERE empno >= :h_empno-50 AND empno <= :h_empno+50;
        EXEC SQL OPEN DB_CUR;

        if(sqlca.sqlcode != 0)
             goto LB_DBERROR;
        EXEC SQL WHENEVER SQLERROR
             goto LB_DBERROR ;
        EXEC SQL WHENEVER NOT FOUND
             Do break ;

        while(1) {
              EXEC SQL FETCH DB_CUR
              INTO    :h_empno,
                      :h_ename,
                      :h_job,
                      :h_date,
                      :h_mgr,
                      :h_sal,
                      :h_comm,
                      :h_deptno;

                fbchg_tu(rcvbuf, EMPNO,  i,(char *)&h_empno, 0);
                fbchg_tu(rcvbuf, MGR,    i,(char *)&h_mgr, 0);
                fbchg_tu(rcvbuf, SAL,    i,(char *)&h_sal, 0);
                fbchg_tu(rcvbuf, DEPTNO, i,(char *)&h_deptno, 0);
                fbchg_tu(rcvbuf, COMM,   i,(char *)&h_comm, 0);
                fbchg_tu(rcvbuf, ENAME,  i,(char *)h_ename, 0);
                fbchg_tu(rcvbuf, JOB,    i,(char *)h_job, 0);
                fbchg_tu(rcvbuf, DATE,   i,(char *)h_date, 0);

                i++;
        }

        if (i < 1)
                goto LB_DBERROR;

        EXEC SQL CLOSE DB_CUR;

        tpreturn(TPSUCCESS, 0L, (char *)rcvbuf, 0L, 0L);

        LB_DBERROR :
                EXEC SQL WHENEVER SQLERROR CONTINUE;
                EXEC SQL CLOSE DB_CUR ;
                svc_error(ORA, sqlca.sqlcode, sqlca.sqlerrm.sqlerrmc, 0L) ;

        LB_TMAXERROR :
                EXEC SQL WHENEVER SQLERROR CONTINUE;
                EXEC SQL CLOSE DB_CUR ;
                svc_error(TMX, tperrno, "", 0L) ;
}

FDLUPDATE( TPSVCINFO *msg )
{

        FBUF *rcvbuf ;
        int i, occurrence;
        rcvbuf = (FBUF *)msg->data;
        h_empno = h_mgr = h_sal = h_comm = h_deptno = 0;

        memset( h_ename, 0x00, sizeof( h_ename ) );
        memset( h_job, 0x00, sizeof( h_job ) );
        memset( h_date, 0x00, sizeof( h_date ) );

        occurrence = fbkeyoccur(rcvbuf, EMPNO);

        for (i=0; i< occurrence; i++) {
             fbget_tu ( rcvbuf, EMPNO, i, (char *)&h_empno, 0);
             fbget_tu ( rcvbuf, ENAME, i, (char *)h_ename, 0);
             fbget_tu ( rcvbuf, JOB,   i, (char *)h_job, 0);
             fbget_tu ( rcvbuf, MGR,   i, (char *)&h_mgr, 0);
             fbget_tu ( rcvbuf, SAL,   i, (char *)&h_sal, 0);
             fbget_tu ( rcvbuf, COMM,  i, (char *)&h_comm,0);
             fbget_tu ( rcvbuf, DEPTNO,i, (char *)&h_deptno,0);
             fbget_tu ( rcvbuf, DATE , i, (char *)h_date, 0 );

             EXEC SQL UPDATE emp
             SET ename = nvl(:h_ename, ename),
                 job   = nvl(:h_job, job),
                 mgr   = :h_mgr,
                 hiredate  = nvl(to_date(:h_date,'yyyymmdd'), hiredate),
                 sal   = :h_sal,
                 comm  = :h_comm,
                 deptno = :h_deptno
             WHERE empno = :h_empno;

             if(sqlca.sqlcode != 0)
                      goto LB_DBERROR;

             EXEC SQL WHENEVER SQLERROR
                      goto LB_DBERROR;

             EXEC SQL WHENEVER NOT FOUND
                      goto LB_DBERROR;
        }
             tpreturn(TPSUCCESS, 0L, (char *)rcvbuf, 0L, 0L);

        LB_DBERROR :
             EXEC SQL WHENEVER SQLERROR CONTINUE;
             svc_error(ORA, sqlca.sqlcode, sqlca.sqlerrm.sqlerrmc, 0L) ;
}

/*********************************************************************
 * Error Handling: If a service error occurs, the error will be entered in a buffer and then sent to a client.
 ********************************************************************/
void svc_error(long type, long err_code, char *msg, long tmp) {
        FBUF *transf;
        char *svcname;
        char err_msg[100];
        char temp[100];
        int i = 0;

        printf("type ==>[%ld]\n", type);
        printf("err_code ==>[%ld]\n", err_code);
        printf("msg ==>[%s]\n",  msg);
        strcpy(err_msg, msg);

        if ((transf = (FBFR *)tpalloc("FML", NULL, 0)) == NULL) {
             printf("tpalloc failed! errno = %d\n", tperrno);
        }

        switch(type) {
            case INP:
                 switch(err_code) {
                       case -1000:
                            strcpy(err_msg, "The user has no privilege.");
                            break;
                       default:
                            strcpy(err_msg,
                                   "An input error message has not been registered.);
                 }
                 break;
            case ORA:
                 if (strlen(err_msg)== 0)  strcpy(err_msg, sqlca.sqlerrm.sqlerrmc);
                 break;
            case TMX:
                 if (strlen(err_msg)== 0) strcpy(err_msg, tpstrerror(tperrno));
                 break;
            case APP:
                 if (strlen(err_msg)== 0) {

                 /* For err_mssg="", an error message is set. ******/
                 switch(err_code) {
                       case -500:        /* SYSTEM-related error */
                            strcpy(err_msg, "Failed to create a file.");
                            break;
                        case -502:
                            strcpy(err_msg, "Could not call an internal service.");
                            break;
                        case -504:
                            strcpy(err_msg, "socket communication error.");
                            break;
                        case -505:  /* When a change was made in another transaction */
                        /* "[%s] was changed in another transaction after it was queried.
                         \n\nHandle it after querying it again.": Handling in CLIENT */
                            strcpy(err_msg, "does not exist.");
                            break;
                         case -5002:
                              strcpy(err_msg, "Contact with a technical team.");
                              break;
                         default:
                              strcpy(err_msg,
                               "An application error message has not been registered.");
                    }
                }
                break;
        }

        /* ROLLBACK        */
        EXEC SQL WHENEVER SQLERROR CONTINUE;
        EXEC SQL ROLLBACK;

        fbchg_tu ( transf, E_TYPE,  i, (char *)&type,0);
        fbchg_tu ( transf, E_CODE,  i, (char *)&err_code,0);
        fbchg_tu ( transf, E_MSG,  i, (char *)err_msg,0);
        fbchg_tu ( transf, E_TMP,  i, (char *)&tmp,0);

        tpreturn(TPFAIL, 0, (char *)transf, 0L, 0L);
}
Makefile

The following is an example Makefile that builds emp_c.pc into a Tmax application.

include $(ORACLE_HOME)/precomp/lib/env32.mk
ORALIBDIR = $(LIBHOME)
ORALIB = -L/home/oracle/OraHome/lib32/ -lclntsh  -lld -lm
         `cat /home/oracle/OraHome/lib32/sysliblist`  -lm  -lc_r -lpthreads
TARGET  = emp_c
APOBJS  = emp_c.o
NSDLOBJ = $(TMAXDIR)/lib/sdl.o
#CC
CC=cc

#Oracle
LIBS    = -lsvr -loras

OBJS    = $(APOBJS) $(SVCTOBJ)
SVCTOBJ = $(TARGET)_svctab.o

CFLAGS  = -q32 -O -I$(TMAXDIR)
LDFLAGS = -brtl
APPDIR  = $(TMAXDIR)/appbin
SVCTDIR = $(TMAXDIR)/svct
TMAXLIBDIR  = $(TMAXDIR)/lib
 #
.SUFFIXES : .c

.c.o:
                $(CC) $(CFLAGS) $(LDFLAGS) -c $<

all: $(TARGET)

$(TARGET): $(OBJS)
                $(CC) $(CFLAGS) $(LDFLAGS) -L$(TMAXLIBDIR) -o $(TARGET)
                -L$(ORALIBDIR)
                $(ORALIB) $(OBJS) $(LIBS) $(NSDLOBJ)
                mv $(TARGET) $(TMAXDIR)/appbin

$(APOBJS): $(TARGET).pc
                proc iname=emp_c include=$(TMAXDIR)
                define=__LINUX_ORACLE_PROC__
                $(CC) $(CFLAGS) $(LDFLAGS) -c $(TARGET).c

$(SVCTOBJ):
                touch $(SVCTDIR)/$(TARGET)_svctab.c
                $(CC) $(CFLAGS) $(LDFLAGS) -c $(SVCTDIR)/$(TARGET)_svctab.c
#
clean:
                -rm -f *.o core $(TARGET) $(TARGET).lis