c programming manual

8/11/2019 C Programming Manual

1/154

____________________Inter.Pel 6.6

____________________

C Programming Manual

____________________

0102-660-02-CPRG6600


2/154

The information contained in this document is subject to revision without prior notice and shall

not be regarded as binding on SOPRA. The rights relative to the use of the software described

in this document are granted as part of the licensing contract and the software shall be used

only in accordance with the terms of that contract. Any reproduction or transmission in any

form or by any process whatever (electronic or mechanical, photocopy and recording included)

and for any purposes other than the personal use of the purchaser without the written

authorization of SOPRA is strictly prohibited.

Copyright 2003 SOPRA.

All rights reserved. All trademarks registered.

November 2003.


3/154

CONTENTS

1. ABOUT THIS MANUAL 1

1.1. Abstract 1

1.2. Content 1

1.3. Reading guidelines 1

2. DOCUMENTATION 2

3. INTERFACE PRESENTATION 3

4. C- API PRIMITIVES 4

4.1. Presentation 4

4.2. List of API primitives 5

4.3. How to use the data structure for primitive calls 6

4.4. Sequential processing of a set of selected transfers 9

4.5. Primitive calls layout 10

4.6. Error reporting on API primitives 10

4.7. Description of API primitives 11

4.7.1. ItpSessionOpen, ItpSessionOpenExt 11

4.7.2. ItpInit 13

4.7.3. ItpXferPut 14

4.7.4. ItpXferGet 17

4.7.5. ItpXferUpdate 20

4.7.6. ItpXferDelete 23

4.7.7. ItpXferUnlock 25

4.7.8. ItpXferOpenSet 27

4.7.9. ItpXferGetNext 28

4.7.10. ItpXferCloseSet 324.7.11. ItpXferCancel 33

4.7.12. ItpXferSuspend 35

4.7.13. ItpXferResume 38

4.7.14. ItpEnd and ItpSessionClose 39

4.7.15. ItpErrMsg 40


4/154

CONTENTS C Programming Manual Page iii____________________________________________________ ______________________________________________

Inter.Pel 6.6 SOPRA.

5. EXIT FUNCTIONS 41

5.1. Presentation 41

5.2. List of exits functions 42

5.2.1. Network connection exits 42

5.2.2. Transfer checking 42

5.2.3. Post-transfer processing 43

5.2.4. Inter.Pel logging activity 43

5.2.5. Inter.Pel statistics activity 43

5.2.6. PeSIT protocol exit function 43

5.2.7. ETEBAC3 exit functions 44

5.2.8. ODETTE exit function 44

5.2.9. FTP exit function 44

5.2.10. Identification check for network client connection request 44

5.2.11. User Access Control Exits 455.2.12. User Login Parameters Exits 45

5.2.13. Generic protocol connection Exit 45

5.2.14. ETEBAC5 exit functions 46

5.3. Transfer exit scheduling order 47

5.4. Using guidelines 47

5.5. Description of exits functions 48

5.5.1. ExitBeginConnexion 48

5.5.2. ExitBeginSend1 49

5.5.3. ExitBeginReceive1 50

5.5.4. ExitBeginSend2 515.5.5. ExitBeginReceive2 52

5.5.6. ExitEndSend 53

5.5.7. ExitEndReceive 54

5.5.8. ExitCSLogin 55

5.5.9. ExitLogArchived 56

5.5.10. ExitLogMessage 57

5.5.11. ExitStatArchived 58

5.5.12. ExitStatMessage 59

5.5.13. ExitPesitPreConnection 60

5.5.14. ExitPesitMsg 61

5.5.15. Et3EncodeParameters 62

5.5.16. Et3DecodeParameters 63

5.5.17. ExitOdtGetAppli 64

5.5.18. ExitFtpGetAppli 66

5.5.19. ExitCheckUserLogin 68

5.5.20. ExitCheckUserAccess 69

5.5.21. ExitCheckFileAccess 71

5.5.22. ExitCheckUserLogout 72

5.5.23. ExitCheckXferRequest 73

5.5.24. ExitLoginParam 74

5.5.25. ExitNetConnReq 75

5.5.26. ExitNetConnResp 76

5.5.27. ExitProtocolConnection 77

5.5.28. Et5ExitConnectInd 79

5.5.29. Et5ExitCreateInd 80


5/154

CONTENTS C Programming Manual Page iv____________________________________________________ ______________________________________________


5.5.30. Et5ExitSelectInd 81

5.5.31. Et5ExitOpenInd 82

5.5.32. Et5ExitDtfEndInd 83

5.5.33. Et5ExitTransEndInd 84

5.5.34. Et5ExitTransEndInd 85

6. API APPENDIX 86

6.1. Description of API data structures 86

6.2. Parameters used to submit or update a file transfer 105

6.2.1. ItpPelPut_t 105

6.2.2. ItpPelLotPut_t 106

6.2.3. ItpPesitPut_t 107

6.2.4. ItpEt3Put_t 109

6.2.5. ItpOdtPut_t 110

6.2.6. ItpEtb5Put_t 1116.2.7. ItpFtpPut_t 113

6.2.8. ItpListPut_t 114

6.2.9. ItpMsgPut_t 115

6.3. Parameters used to retrieve a transfer attributes 116

6.3.1. ItpPelRecord_t 116

6.3.2. ItpPelLotRecord_t 118

6.3.3. ItpPesitRecord_t 119

6.3.4. ItpEt3Record_t 121

6.3.5. ItpOdtRecord_t 123

6.3.6. ItpEtb5Record_t 125

6.3.7. ItpFtpRecord_t 127

6.3.8. ItpListRecord_t 1296.3.9. ItpMsgRecord_t 131

6.6. Parameters used to select file transfers 133

7. EXIT APPENDIX 134

7.1. Description of exits functions data structures 134

7.1.1. exituser.h 134

7.1.2. exitconn.h 135

7.1.3. exitxfer.h 138

7.1.4. exitlog.h 143

7.1.5. exitstat.h 1447.1.6. exitclnt.h 144

7.1.7. exitsecu.h 144

7.1.8. Itpndsp.h 145


6/154

CONTENTS C Programming Manual Page v____________________________________________________ ______________________________________________



7/154

1. ABOUT THIS MANUAL C Programming Manual Page 1____________________________________________________ ______________________________________________


1. ABOUT THIS MANUAL

1.1. Abstract

This manual describes the C user programming interface supplied by Inter.Pel. Itincludes application programming interface (A.P.I.) and exits functionsdescription.

This manual is intended for application programmers familiar with Cprogramming language. It does not discuss the C language, the C run-time libraryand the C execution environment (compiler and system dependencies). Refer to

public reference manuals on C language, and to your platform documentation, fordetailed information on this programming language.

1.2. Content

Section 1 Document abstractSection 2 Presentation of Inter.Pel documentationSection 3 Presentation of Inter.Pel programming interfaceSection 4 Description of API programming interfaceSection 5 Description of exits functions programming interfaceSection 6 Additional information on APISection 7 Additional information on exits functions

1.3. Reading guidelines

To gain basic understanding of Inter.Pel, read Inter.Pel 6.6 Overviewmanual.

User's Guideprovides information on how to use the product for file transfer.

Protocols Guideexplains how to use file transfer protocols with Inter.Pel.

Once your programs are written, you must refer to your platforms Inter.Pelspecific document for details on how to compile and link with the monitor'slibraries.


8/154

2. DOCUMENTATION C Programming Manual Page 2____________________________________________________ ______________________________________________


2. DOCUMENTATION

The Inter.Pel documentation contains two categories of technical publications:

- Generic manuals: they are designed for all platforms running Inter.Pel.- Specific manuals containing platform dependent features. Each platform

is provided with its own set of specific manuals.

Title Type Function

Product Overview Overview Presentation

User's Guide Services How To Use

On-line commands Manual Utilities Operations & Mgmt

Protocols Guide How it works Understanding & Using transfer protocols

Messages & Codes Description Interpreting Information and errors messages

C programming Manual

COBOL programming Manual

Programming Integration of user applications

Installation & Configuration Guide(1) Install & Config Install & Config

Platform Specific Document (1) Specific supplement OS specific features

Getting Started (1) Running a transfer Quick User's Guide

PELISF Manual (2) Utilities Script mode operator's interface

I.H.M. Manual (2) Utilities Graphical operator's interface

PELOP Manual (2) Utilities Character mode operator's interface

(1): Specific manual: one document for each platform.(2): Document provided when the related interface is supplied for the platform.


9/154

3. INTERFACE PRESENTATION C Programming Manual Page 3____________________________________________________ ______________________________________________


3. INTERFACE PRESENTATION

Two types of C programming interfaces are supplied by Inter.Pel:

- Application programming interface (A.P.I.)- Exits functions

The A.P.I. routines (primitives) allow user programs to use Inter.Pels file transferservices.

The user program containing A.P.I. calls must be compiled and linked withInter.Pel libraries. It must be used with an active Inter.Pel.

The API primitives use request/response mode to communicate with Inter.Pel.The response is supplied on the return of primitive calls. On some platforms, a

time-out is fixed for API calls, in order to avoid the indefinite locking of a userprogram on an API call. This parameter sets the maximum delay for a userprogram to wait for the return of an API call. Above this delay, Inter.Pel forces anegative return code (-1) to the primitive call, meaning that the call has failed(Refer to Platform Specific Document for more information).

A.P.I. primitives using and description are supplied in section "4. C- APIPRIMITIVES".

Exits functions are routines that allow to graft user customized processing at pre-defined steps of a file transfer. A different function is defined for each step. Exitsfunctions are automatically scheduled by Inter.Pel. You can use them for checking

purpose if they are called before the transfer completion, or for post-transferprocessing if they are called at the transfer completion.

Exits functions provide means to automate your file transfer operation.

You must recompile the files containing updated exits functions, and link themwith Inter.Pel libraries. The monitor must be restarted to take into account yournew program.

Exits functions are described in section "5. EXIT FUNCTIONS".


10/154

4. C- API PRIMITIVES C Programming Manual Page 4____________________________________________________ ______________________________________________


4. C- API PRIMITIVES

4.1. Presentation

C API primitives are called from C user programs.

They provide following Inter.Pel services:

- Submitting a transfer or a message request- Displaying a transfer or a message requests parameters- Deleting transfers or messages from the mailbox- Listing transfers using multi-criteria on transfers parameters- Canceling a transfer- Suspending a transfer- Restarting a transfer previously suspended

This API has the following characteristics:

- It can only be used when Inter.Pel is active- Its primitives are called from programs written in C- Its primitives communicate with Inter.Pel in request-response mode- Data structures are used to exchange transfer parameters between theprimitives and Inter.Pel

- The parameter structures used as arguments for the primitives calls areallocated in the user program space

- The primitives use Inter.Pel internal objects (sites, applications). Theseobjects must have been created prior to the primitive call, using Inter.Pel

on-line commands or graphical user interfaces. No primitive is supplied forsite or application management- They are available for all protocols currently supported (PEL, PeSIT Hors

SIT D and E, ETEBAC3, ETEBAC5 client, ODETTE, FTP)

This guide describes the primitives, their parameters and how they operate.


11/154



4.2. List of API primitives

The primitives listed below are prototyped, and their arguments described, in the

header file "itpapi.h" (this is the naming for UNIX platforms; for other platforms,refer to the specific document for file naming and location).

Primitive name Function supplied

ItpInit

ItpSessionOpen

ItpSessionOpenExt

Used to open a session (communication pipe) with Inter.Pel

ItpEnd

ItpSessionClose

Close the session previously opened with Inter.Pel

ItpXferPut Creates a transfer or a message request, and returns a local

transfer identifier (numeric)ItpXferGet Reads a transfer or a message request parameters saved in a

mailbox record, using transfer local identifier.

This reading can lock or not the corresponding mailbox

record

ItpXferUnlock Unlocks a mailbox record after a read with lock

ItpXferUpdate Updates a transfer request

ItpXferDelete Deletes a transfer or a message request from the mailbox

ItpXferOpenSet Selects a set of transfer requests using multi-criteria on

transfer parameters

ItpXferGetNext Reads parameters of transfer requests previously selected with

ItpXferOpenSet

ItpXferCloseSet Deselects the previously selected set of transfersItpXferCancel Cancels a transfer request. The transfer is switched into

"canceled" state

ItpXferSuspend Freezes a transfer processing

ItpXferResume Restarts a previously suspended transfer

ItpErrMsg Utility function used to retrieve the meaning of the last error

encountered by Inter.Pel

To use these primitives, you must include the header file itpapi.hin your sourcefiles:

#include

All the primitives return an integer:

- Negative integer (-1) if an error condition is encountered- 0 or positive integer if the primitive call is successful

The error code is reported in a global integer variable named ErrCod, the value ofErrCod is meaningless if the return integer is not equal to (-1). The correspondingerror message is obtained by calling the primitive ItpErrMsg()with ErrCod asargument.


12/154



Five different data structures are used by the API primitives:

ItpXferPut_t : used to transmit transfer request parametersItpXferIdent_t : used to transmit transfer local identifier

ItpXferRecord_

t : used to retrieve transfer attributes read in the mailboxItpMsgRecord_t : used to put or retrieve message requests into or from themailbox

ItpXferSelect_t : used to transmit selection criteria

Before using any primitive, a user program must open a session with the monitorusing the ItpSessionOpen()function (or an equivalent function). Close thesession at the end of the program using ItpSessionClose().

4.3. How to use the data structure for primitive calls

Two data structures are supplied in C union structures: ItpXferPut____tandItpXferRecord____t . Their content depends on the protocol used. This paragraphdescribes guidelines for their using.

The two illustration examples described in this paragraph deal with the using ofItpXferPut_t andItpXferRecord_trespectively with ItpXferPutandItpXferGetprimitives. They are used in the same manner for the other primitives.

ItpXferPut()primitive uses ItpXferPut_tstructure to transmit the transferrequest parameters. ItpXferPut_tstructure is declared as follow:

typedef struct{ short protocol;

short type; union { ItpPelPut_t pel; ItpEtb3Put_t etb3; ItpPelLotPut_t lot; ItpPesitPut_t pesit; ItpOdtPut_t odt; ItpEtb5Put_t etb5; ItpFtpPut_t ftp; ItpListPut_t list; ItpMsgPut_t msg;

} param; unsigned char user_state;char filler[100];

} ItpXferPut_t;


13/154



The following diagram presents how to fill the structure according to the transferprotocol used.

Protocol Type Substructure used CommentsPEL TYPE_TRANS ItpPelPut_t

PEL TYPE_LOTS ItpPelLotPut_t TYPE_LOTS defined for PEL only

PEL TYPE_POLL ItpPelLotPut_t TYPE_POLL defined for PEL only

PESIT TYPE_TRANS ItpPesitPut_t

ETEBAC3 TYPE_TRANS ItpEtb3Put_t

ODETTE TYPE_TRANS

TYPE_EERP

ItpOdtPut_t TYPE_EERP defined for ODETTE only

ETEBAC5 TYPE_TRANS ItpEtb5Put_t

FTP TYPE_TRANS ItpFtpPut_t

LIST TYPE_LIST ItpListPut_t To submit a Broadcasting request

PESIT TYPE_MSG ItpMsgPut_t Message request. PeSIT HS E protocols

only

PESIT,

ODETTE

TYPE_EERP ItpMsgPut_t EERP request. PeSIT HS E and Odette

protocols only

ItpXferGetprimitive uses ItpXferRecord_tunion structure to retrieve transfer

request parameters. This structure is declared as follow:

typedef struct{ short protocol; short type; union { ItpPelRecord_t pel; ItpEtb3Record_t etb3; ItpPelLotRecord_t lot; ItpPesitRecord_t pesit;

ItpOdtRecord_t odt; ItpEtb5Record_t etb5; ItpFtpRecord_t ftp; ItpListRecord_t list; ItpMsgRecord_t msg; } record;

unsigned char user_state;char filler[100];

} ItpXferRecord_t;


14/154



The following diagram presents in which substructure you will find the transferparameters.

Protocol Type Substructure to use Comments

PEL TYPE_TRANS ItpPelRecord_t

PEL TYPE_LOTS ItpPelLotRecord_t TYPE_LOTS defined for PEL only

PEL TYPE_POLL ItpPelLotRecord_t TYPE_POLL defined for PEL only

PESIT TYPE_TRANS ItpPesitRecord_t

ETEBAC3 TYPE_TRANS ItpEtb3Record_t

ODETTE TYPE_TRANS

TYPE_EERP

ItpOdtRecord_t TYPE_EERP defined for ODETTE only

ETEBAC5 TYPE_TRANS ItpEtb5Record_t

FTP TYPE_TRANS ItpFtpRecord_t

LIST TYPE_LIST ItpListRecord_t

PESIT TYPE_MSG ItpMsgRecord_t Message request. PeSIT HS E protocols

only

PESIT,

ODETTE

TYPE_EERP ItpMsgRecord_t EERP request

PeSIT HS E and Odette protocols only

Message requests are a special type of transfer request in the sense that theyinvolve in-line (usually short) message transfer in stead of file transfer. There aretwo categories of message requests : application messages and end-to-endresponse message (also known as EERP message). In the current implementation,application message is supported only by PeSIT HS E protocol, and EERPmessage is supported by both PeSIT HS E and Odette protocols.


15/154



4.4. Sequential processing of a set of selected transfers

You can select a set of transfer requests, and read or delete them sequentially.

This requires three steps:

1- Selection of a set of transfer requests

#include ItpXferSelect____t sel;ret_cod =ItpXferOpenSet(&sel);

You must first set the selection criteria in the selection structureItpXferSelect____t .

2- Reading selected transfer requests

int option;ItpXferRecord____t xfer;ret_cod =ItpXferGetNext(option, &xfer);

Use the optionparameter (XFER_LOCK or 0) to indicate whetheryou want a read with or without lock.

ItpXferGetNext()reads sequentially the selected transfer requests,and copies their attributes in the structure ItpXferRecord____t.

Only one transfer is retrieved per ItpXferGetNext() call. The functionreturns E____FEOFafter all selected transfers are read.

3- Releasing the interface resources associated with the set

ret_cod = ItpXferCloseSet();

After reading with lock a selected transfer (step 2), you can either:

- Call application specific function

- Update the transfer request (by calling ItpXferUpdate()primitive)- Delete the last transfer read (by calling ItpXferDelete()primitive)


16/154



4.5. Primitive calls layout

User programs always start the communication with Inter.Pel by calling

ItpSessionOpen()primitive, and ends the communication by callingItpSessionClose()primitive. In between the two calls, the program can requireInter.Pel services listed in subsection "4.1. Presentation".

The following layouts provide guidelines for the programming of these services.

Action C routines layout In Out comments

submitting a

transfer

ItpSessionOpen(char *user, char *pass)

ItpXferPut(ItpXferPut_t *ptr)

ItpSessionClose()

I

- ItpXferPut_t declared and initialized

Displaying

transfer

parameters


ItpXferGet(int option,

ItpXferIdent_t *id,

ItpXferRecord_t *xfer)

ItpSessionClose()

I

I

O

- Option = XFER_LOCK|0

- ItpXferIdent_t and ItpXferRecord_t

declared and initialized

Deleting

transfers from

mailbox


ItpXferOpenSet(ItpXferSelect_t *s)

ItpXferGetNext ( int option,

ItpXferRecord_t *xfer)

ItpXferDelete()

ItpXferCloseSet ()

ItpSessionClose()

I

I

O

- ItpXferSelect_t declared and initialized

- Option=XFER_LOCK

- ItpGetNext retrieve the next record selected,

starting from the first one

- One can sequentially retrieve selected

records with ItpGetNext until reaching a

given one

- ItpXferDelete purges the last selected

record

- The user can loop on get next/delete until

EOF (the error condition on get next isE_FEOF)

Suspending a

transfer


ItpXferSuspend( ItpXferIdent_t *id)

ItpSessionClose()

I

- The transfer request must be in one of the

following states:

XFER_TO_BEGIN

XFER_PROGRESSING

XFER_SERVICING

XFER_DELAYED

Restarting a

suspended or

frozen transfer


ItpXferResume( ItpXferIdent_t *id)

ItpSessionClose()

I

- The transfer request must be in the state:

XFER_SUSPENDED

XFER_FROZEN

Canceling a

transfer


ItpXferPut( ItpXferIdent_t *id)

ItpSessionClose()

I

- The transfer request must be in one of the

following states:

XFER_TO_BEGIN

XFER_FROZEN

XFER_SUSPENDED

XFER_DELAYED

4.6. Error reporting on API primitives

Inter.Pel uses a global variable (integer named ErrCod) to report error conditionsto user programs.

The user program uses ItpErrMsg() routine to obtain the explanation of the last

API error reported by Inter.Pel.


17/154



4.7. Description of API primitives

4.7.1. ItpSessionOpen, ItpSessionOpenExt

Syntax

int ItpSessionOpen(char *user, char *password)

int ItpSessionOpenExt(char *profile_name, char *user, char *password)

Return value

0 : If the call is successful

-1 : If an error is detected. The error type is indicated in global variable(ErrCod). ItpErrMsg() function returns the text of the error. ErrCodvariable is declared and automatically set by Inter.Pel

Description

ItpSessionOpen function is used to open a sessionwith the monitor beforeusing any other API primitive. It provides access security features, namelyfor the using of API interface in client/server mode. You can check username and password with a specific exit function: ExitCSLogin(). Close the

session at the end of the program using ItpEnd() or ItpSessionClose().

ItpSessionOpenExt is used in the same way, with following additionalfeature: you can choose which monitor to use between among. It uses"profile_name" parameter to identify the section in the clientCSCONFIG.INIfile that describes the session with the target Inter.Pel.

Example: Inter.Pel monitor "Monitor_1" is described by the followingsection of the CSCONFIG.INI file on the Inter.Pel client station:

[Monitor_1]HostName=193.56.234.29

Port =23000

If the client station wants to open a session with this Inter.Pel, theprofile_name must be Monitor_1.

Both ItpSessionOpen() and ItpSessionOpenExt() primitives open a session:you must use only one of them.

Open session and close session functions must be called only once in eachsession.

Both ItpSessionOpen and ItpSessionOpenExt() are usually used forclient/server mode of communication.


18/154



Note

ItpSessionOpen() uses a default section description referenced by Inter.Pel

environment variable P_CS_SERVER, to define the profile of the session user.This variable is defined in the running environment of Inter.Pel. Refer to your

platform specific document for the description of this parameter.

On the other hand, ItpSessionOpenExt function transmits the user profile in itsarguments. If profile_name is not supplied (NULL pointer), Inter.Pel uses thedefault user profile defined by the environment variable P_CS_SERVER.ItpSessionOpenExt() then operates like ItpSessionOpen().

Example

#include #include char profile_name[15], user_name[10], password[10];

int main(int argc, char *argv[]){

int retcod;...

/* set the values of arguments */...retcod = ItpSessionOpenExt(profile_name, user_name, password);

if (retcod == -1)printf("error text = %s\n", ItpErrMsg());...

}


19/154



4.7.2. ItpInit

Syntax

int ItpInit(void)

Superseded by ItpSessionOpenand ItpSessionOpenExt.

Return value


-1 : If an error is detected. The error type is indicated in global variableErrCod. ItpErrMsg function returns the text of the error. ErrCod

variable is declared and automatically set by Inter.Pel

Description

This primitive is used to open a sessionwith the monitor before using anyother primitive. Close the session at the end of the program usingItpSessionClose().

The open session and close session functions must be called only once ineach session.

No argument is supplied for this function.

Note

In version 6.3 and later releases, it is advisable to use only ItpSessionOpen(see previous section) since ItpInit has been retained only for compatibilitywith previous versions.

Example

#include #include ...int main(int argc, char *argv[]){

int retcod;...retcod = ItpInit();if (retcod ==-1)

printf("error text = %s\n", ItpErrMsg());...

}


20/154



4.7.3. ItpXferPut

Syntax

long ItpXferPut(ItpXferPut_t *param)

See "API appendix" section for the full description of ItpXferPut_t.

Return value

>0 : If the call is successful. This number is the local identifier of thetransfer created

-1 : If an error is detected. The error type is indicated in global variable

ErrCod. ItpErrMsg function returns the text of the error. ErrCodvariable is declared and automatically set by Inter.Pel

Description

This function is used to create a transfer request .

The attributes describing the transfer request must be supplied in thearguments of the primitive. Among them are:

- File attributes (file structure, record description, ...)

- Transfer direction (sending or receiving)- Origin and destination sites for the transfer- Protocol parameters- Transfer monitoring parameters (date to begin, retry count, ...)

In return, you receive an integer representing the local identifier of therequest. This identifier is used for subsequent operations on the request.

Before calling the function, the user program must declare and initializeItpXferPut_tstructure (see itpapi.h header file) that contains all the

parameters of a transfer request (see note).

Parameters not supplied must be initialized to 0 for numeric areas, and anempty string (length=0)for string characters.

Before creating the transfer request, Inter.Pel completes the parametersmissing in the request. If an application name has been supplied in therequest, Inter.Pel set the missing parameters with the value of correspondingattributes contained in that application object. If some parameters are stillunresolved, default values, either supplied by the API or fixed internally inthe monitor, are used. (see "API appendix" section).

The API interface checks the validity of the parameters before creating thetransfer request.

If an invalid parameter is found, the creation is rejected and an errorreturned.


21/154



Note

1. The parameters supplied for a transfer request depend on the protocol andtype of request:

- For the PeSIT protocol (type D and E), the required parameters aredefined in substructure ItpPesitPut_t

- For the PEL protocol (including type PEL1), they are defined insubstructure ItpPelPut_t

- For the LOTS command of the PEL protocol (protocol=PEL andtype=TYPE_LOTS or type=TYPE_POLL ), they are defined insubstructure ItpPelLotPut_t

- For the ETEBAC3 protocol, they are defined in substructure

ItpEtb3Put_t

- For the ODETTE protocol, they are defined in substructureItpOdtPut_t

- For the ETEBAC5 protocol, they are defined in substructureItpEtb5Put_t

- For the FTP protocol, they are defined in substructure ItpFtpPut_t

- For a broadcasting request, they are defined in substructureItpListPut_t

- For a message request, they are defined in substructure ItpMsgPut_t

You must choose the structure to fill up according to the protocol andtype of request.

2. The syntax and semantic of each transfer parameter are explained in "APIappendix"section.


22/154



Example

/* submitting a transfer request to send a file using PEL protocol:- origin alias site name: ORIG_SIT- destination alias site name: DEST_SIT- application used: APPLI_X- name of the file to send including access path:

FILE_X (= ///.../name) is the full file name string.*/...

#include #include ...

int main(int argc, char *argv[]){ItpXferPut_t xput;long ident;char user_name[10], password[10];

.../* set the values of arguments */

memset( &xput, 0, sizeof(ItpXferPut_t));

xput.protocol = ITP_PROTO_PEL;xput.type = ITP_TYPE_TRANS;strcpy(xput.param.pel.org_alias, "ORIG_SIT");strcpy(xput.param.pel.dest_alias, "DEST_SIT");strcpy(xput.param.pel.appli, "APPLI_X");strcpy(xput.param.pel.pathname, FILE_X);...

/* opening the session */if (ItpSessionOpen(user_name, password)() == -1) {

printf("Open session failed. Error msg= %s\n", ItpErrMsg());exit(1);}

/* submitting the transfer */

if ( (ident = ItpXferPut(&xput)) == -1)printf("Transfer request failed. Error Msg=%s\n", ItpErrMsg());

elseprintf("Transfer request successful. Local ident=%ld\n", ident);

/* closing the session */ItpSessionClose();...

}


23/154



4.7.4. ItpXferGet

Syntax

int ItpXferGet(int option, ItpXferIdent_t *ident, ItpXferRecord_t *xfer)

See "API appendix"section for the full description of the structures used.

Return value


-1 : If an error is detected. The error type is indicated in global variableErrCod. ItpErrMsg function returns the text of the error.

ErrCod variable is declared and automatically set by Inter.Pel

Description

This function reads a transfer requestdefined by its local identifier, andcopies the transfer parameters in the structure ItpXferRecord_t. The localidentifier is supplied in the structure ItpXferIdent_t.

You must declare and enter the arguments ident(transfer request identifier)and option(read option) before calling the function. You must also declareand initialize an ItpXferRecord_tstructure to receive the record that has

been read.

Refer to API appendix section for the description of ItpXferRecord_tstructure, and the meaning of its parameters.

The optionparameter (XFER_LOCK or 0) indicates whether the read iswith or without lock. If the transfer request reading is followed by an updateor delete operation, the lock option is mandatory.

Only one lock can be enabled at a time: a lock automatically cancelsanearlier lock.

If an update or delete operation is successful, the record is automaticallyunlocked afterwards.


24/154



Note

The ItpXferRecord_tstructure is made of a combination of seven

substructures, depending on the protocol and type of transfer request. Toread the data, you therefore need to test the protocol and type of request

before selecting the substructure to use:

- For protocol=PESIT and type=TYPE_TRANS, use ItpPesitRecord_tsubstructure

- For protocol=PEL and type=TYPE_TRANS, use ItpPelRecord_tsubstructure

- For protocol=PEL and type=TYPE_LOTS or TYPE_POLL , useItpPelLotRecord_t substructure

- For protocol=ETEBAC3 and type=TYPE_TRANS, useItpEtb3Record_t substructure

- For protocol=ODETTE and type=TYPE_TRANS, useItpOdtRecord_t substructure

- For protocol=ODETTE and type=TYPE_EERP, use ItpOdtRecord_tsubstructure

- For protocol=ETEBAC5 and type=TYPE_TRANS, useItpEtb5Record_t substructure

- For protocol=FTP and type=TYPE_TRANS, use ItpFtpRecord_tsubstructure

- For type=TYPE_LIST , use ItpListRecord_t substructure

- For type=TYPE_MSG or type=TYPE_EERP, use ItpMsgRecord_tsubstructure


25/154



Example

/* This example reads a transfer request corresponding to local identifier N */...

#include #include ...


ItpXferRecord_t xget;ItpXferIdent_t ident;char user_name[10], password[10];

int option;.../* initialize the arguments */

memset( &xget, 0, sizeof(ItpXferRecord_t));memset( &ident, 0, sizeof(ItpXferIdent_t));option = 0ident.local_ident = N;...



/* Retrieving transfer parameters*/if ( ItpXferGet(option, &ident, &xget)) == -1)

printf("Get failed. Error Msg=%s\n", ItpErrMsg());else {

printf("Get successful\n");printf("protocol=%hd\n", xget.protocol);printf("type=%hd\n", xget.type);...

}...switch(xget.protocol) {

case ITP_PROTO_PEL:...case ITP_PROTO_PHSD:...

}..


}


26/154



4.7.5. ItpXferUpdate

Syntax

int ItpXferUpdate(ItpXferPut_t *param)

See "API appendix"section for the full description of the structure used.

Return value


-1 : If an error is detected. The error type is indicated in global variableErrCod. ItpErrMsg function returns the text of the error. ErrCodvariable is declared and automatically set by Inter.Pel

Description

This function is used to modify a transfer request.

The operation must be preceded by a successful call to a read function(using ItpXferGet or ItpGetNext) with lock option. For a read with lock, setthe option parameter to XFER____LOCK .

Automatic locking mechanism is used:

- any concurrent read with lock for the same record initiated by another user is then prevented by the error condition: E____FRLOCKED

- the lock is automatically disabled by a subsequent access to themailbox that is initiated by the same user program

The transfer request can be modified according to the following rules:

Allowed transfer state to updatea request

New allowed parameters

ITP_XFER_ACKEDITP_XFER_ENDED

option_fileuser_state

ITP_XFER_CANCELED option_file

user_stateITP_XFER_FROZENITP_XFER_DELAYEDITP_XFER_TO_BEGIN

All the parameters

ITP_XFER_TO_SIGN All the parameters

The lock on the transfer request record is automatically disabled after asuccessful update.

After reading the transfer request, the user program filled the ItpXferPut_tstructure's parameters, and calls ItpXferUpdate.


27/154



The parameter values that have been changed transmit their new value to thecorresponding attributes in the transfer request.

During the update, unmodified parameters keep their former value.

Caution:A parameter assigned with the value 0 (if integer), or empty string(if character string) are updated in the transfer request.

There is no one-to-one relationship between the read parameters(ItpXferRecord_t) and the write/modify parameters (ItpXferPut_t). Sometransfer parameters can be entered or modified by the monitor only. Usershave read-only access on these parameters.

In addition, the structure used for modification is the same as for creating arecord (ItpXferPut_t) but the protocol and type cannot be modified.

Note

1. The parameters required for a transfer request depend on the protocol andtype of request:

- For the PeSIT protocol (type D and E), the required parameters aredefined in substructure ItpPesitPut_t

- For the PEL protocol (type PEL1 included), they are defined insubstructure ItpPelPut_t

- For the LOT request type which is defined only for PEL protocol

(protocol=PEL and type=TYPE_LOTS or type=TYPE_POLL ), theyare defined in substructure ItpPelLotPut_t


- For the ODETTE protocol, they are defined in substructureItpOdtPut_t


You must therefore choose the structure according to the protocol andtype of request.

2. The syntax and semantics of each transfer parameter are explained in"API appendix"section.

3. The record locking can also be disabled by a call to ItpXferUnlock()primitive.


28/154



Example

/* This example reads a transfer request corresponding to localidentifier N and updates it */...


ItpXferRecord_t xget;ItpXferIdent_t ident;ItpXferPut_t xput;

char user_name[10], password[10];int option;...

/* initialize the arguments */memset( &xget, 0, sizeof(ItpXferRecord_t));memset( &ident, 0, sizeof(ItpXferIdent_t));option = XFER_LOCKident.local_ident = N;...




printf("Get with lock failed. Error Msg=%s\n", ItpErrMsg());else

printf("Get with lock successful\n");...

/* Update the parameters in ItpXferPut_t structure */memset(&xput, 0, sizeof(ItpXferPut_t));... = or ...

/* Send the updated structure */if ( ItpXferUpdate(&xput) == -1)

printf("Update request failed. Error Msg=%s\n", ItpErrMsg());else

printf("Update request successful\n");...


}


29/154



4.7.6. ItpXferDelete

Syntax

int ItpXferDelete(void)

Return value



Description

This function deletes a transfer request.

The operation must be preceded by a successful call to a read function(using ItpXferGet or ItpXferGetNext) with lock option. For a read with lock,set the option parameter to XFER_LOCK.

Any concurrent read with lock for the same record is then prevented by theerror condition: E_FRLOCKED.

If a transfer request is deleted during the file transfer, the transfer will beaborted and the request deleted.

Note

If you delete a transfer request record after reading it by ItpXferGetNext(),you must have previously select that record using ItpOpenSet() primitive.

In this case, the primitives are called according to the following sequence:...ItpOpenSet(...)

ItpXferGetNext(option=XFER_LOCK, ...)ItpXferDelete()....


30/154



Example

/* This example reads a transfer request corresponding to local identifier N anddeletes it */

...




memset( &xget, 0, sizeof(ItpXferRecord_t));memset( &ident, 0, sizeof(ItpXferIdent_t));option = XFER_LOCKident.local_ident = N;...

/* opening the session */if (ItpSessionOpen(user_name, password)() == -1)

printf("Open session failed. Error msg= %s\n", ItpErrMsg());




/* Delete */if ( ItpXferDelete() == -1)

printf("Delete request failed. Error Msg=%s\n", ItpErrMsg());else

printf("Delete request successful\n");...


}


31/154



4.7.7. ItpXferUnlock

Syntax

int ItpXferUnlock(void)

Return value


-1 : If an error is detected. The error type is indicated in global variableErrCod. ItpErrMsg function returns the text of the error.ErrCod variable is declared and automatically set by Inter.Pel

Description

This function unlocks a transfer requestthat has been previously read withthe lock option.

Note

None.


32/154



Example

/* This example reads a transfer request corresponding to local identifier N withlock option, and unlocks it */

...




memset( &xget, 0, sizeof(ItpXferRecord_t));memset( &ident, 0, sizeof(ItpXferIdent_t));option = XFER_LOCKident.local_ident = N;...






/* Unlock */if ( ItpXferUnlock() == -1)

printf("Unlock request failed. Error Msg=%s\n", ItpErrMsg());else

printf("Unlock request successful\n");

.../* closing the session */ItpSessionClose();...

}


33/154



4.7.8. ItpXferOpenSet

Syntax

int ItpXferOpenSet(ItpXferSelect_t *select)

See "API appendix" section for the full description of the structure used.

Return value


-1 : If an error is detected. The error type is indicated in global variableErrCod. ItpErrMsg() function returns the text of the error. ErrCodvariable is declared and automatically set by Inter.Pel

Description

This function is used to select a set of transfer requestsaccording to thecriteria specified in the ItpXferSelect_tstructure.

To select all the transfer, the ItpXferSelect_tstructure must be initialized to 0.You must declare and initialize the ItpXferSelect_tstructure.

Note

After a successful selection, transfer requests selected are read sequentiallyby iterative calls of ItpXferGetNext()primitive.

After a successful ItpGetNext() call, you can process the followingoperations:

- Calling once more ItpGetNext() to obtain the next record of theselection

- Delete the read transfer request using ItpXferDelete()- Update the read transfer request using ItpXferUpdate()

Example

See example of paragraph "4.7.9. ItpXferGetNext".


34/154



4.7.9. ItpXferGetNext

Syntax

int ItpXferGetNext(int option, ItpXferRecord_t *xfer)

See "API appendix"section for the full description of the structure used.

Return value


-1 : If an error is detected. The error type is indicated in global variableErrCod. ItpErrMsg() function returns the text of the error. ErrCod

variable is declared and automatically set by Inter.Pel. The ErrCodvalue E_FEOF means that no more transfer records are available

Description

This function is used to read the transfer requestspreviously selected bythe ItpXferOpenSetfunction.

You must declare and specify the optionvariable (read option) beforecalling the function. You must also declare and initialize anItpXferRecord_tstructure to receive the record that has been read.

ItpXferGetNext()function reads the transfer request and filled theItpXferRecord_tstructure detailed in "API appendix"section.

The optionparameter (XFER_LOCK or 0) indicates whether the read iswith or without lock. If the transfer request reading is followed by an updateor delete operation, the lock option is mandatory.

Only one lock can be enabled at a time: a lock automatically cancels anearlier lock.

The lock is automatically disabled on the subsequent access to the mailbox.


35/154



Note

The ItpXferRecord_tstructure consists of a union of seven substructures of

different protocols and types. To read the data, you therefore need to test theprotocol and type before selecting the substructure to be entered:

- For type=TYPE_LIST, use the ItpListRecord_t substructure

- For protocol=PESIT and type=TYPE_TRANS (the only possiblevalue in PeSIT), use the ItpPesitRecord_t structure

- For protocol=PEL and type=TYPE_TRANS, use the ItpPelRecord_tsubstructure

- For protocol=PEL and type=TYPE_LOTS or TYPE_POLL , use the

ItpPelLotRecord_t substructure

- For protocol=ETEBAC3 and type=TYPE_TRANS, use theItpEtb3Record_t substructure

- For protocol=ETEBAC5 and type=TYPE_TRANS, use theItpEtb5Record_t substructure

- For protocol=ODETTE and type=TYPE_TRANS, use theItpOdtRecord_t substructure

- For protocol=FTP and type=TYPE_TRANS, use the ItpFtpRecord_tsubstructure


36/154



Example

/* Description:- select all transfers with PEL protocol that are terminated (status "ended" or"canceled"),- delete among them all transfers in sending mode (direction "out")*/...

#include #include

...

int main(int argc, char *argv[]){ItpXferRecord_t xget;ItpXferSelect_t sel;char user_name[15], password[10];int option;...



/* Selection */memset( &sel, 0, sizeof(ItpXferSelect_t));

sel.state_list_len = 2;sel.state_list_val[0] = ITP_XFER_ENDED;sel.state_list_val[1] = ITP_XFER_CANCELED;sel.protocol = ITP_PROTO_PEL;if ( ItpXferOpenSet(&sel)) == -1)

printf("Selection failed. Error Msg=%s\n", ItpErrMsg());else

printf("Selection successful\n");

option = XFER_LOCK;while (1) {

memset( &xget, 0, sizeof(ItpXferRecord_t));

if (ItpXferGetNext(option, &xget)) == -1)else if (ErrCod == E_FEOF) {

printf("End of selection list reached ! \n");break;

}else

printf("GetNext Error. Error Msg=%s\n", ItpErrMsg());


37/154



if (xget.record.pel.direction == ITP_DIRECTION_OUT) {if ( ItpXferDelete() == -1) ItpXferUnlock(); printf("Delete request failed. Error Msg=%s\n",

ItpErrMsg());else {printf("Delete request successful: ident = %ld\n", xget.record.pel.ident.local_ident); break;}

}}.../* close the selection */ItpXferCloseSet();...


}


38/154



4.7.10. ItpXferCloseSet

Syntax

int ItpXferCloseSet(void)

Return value



Description

This function is used to close the set of transfer requests previously selectedusing the ItpXferOpenSet()function.

Example

See example of paragraph "4.7.9. ItpXferGetNext".


39/154



4.7.11. ItpXferCancel

Syntax

int ItpXferCancel(ItpXferIdent_t *ident)

See "API appendix" section for the description of the structure used.

Return value




Description

This function cancels a transfer requestidentified by its local identifier.The corresponding transfer record is not deleted from the mailbox.

The monitor is processing the transfer request:

If the value of transfer state is ITP_XFER_PROGRESSING orITP_XFER_SERVICING, the transfer is canceled otherwise the

transfer is suspended.

The monitor is not processing the transfer request.The transfer request will be canceled if it is in one of the following states:

ITP_XFER_FROZENITP_XFER_DELAYEDITP_XFER_SUSPENDEDITP_XFER_TO_BEGINITP_XFER_TO_RESTARTITP_XFER_CREATEDITP_XFER_INTERRUPTED

ITP_XFER_PROGRESSINGITP_XFER_SERVICINGITP_XFER_TO_SIGN.

After a successful call, the corresponding transfer state is switched intoITP_XFER_CANCELED.

The transfer request does not need to be locked to perform this operation.


40/154



Note

A call to ItpXferCancelled() with a transfer in any other state returns theerror condition: ErrCod = E_XWRONGSTATE (Invalid transfer state).

Example

See example of paragraph "4.7.12. ItpXferSuspend".


41/154



4.7.12. ItpXferSuspend

Syntax

int ItpXferSuspend(ItpXferIdent_t *ident)


Return value




Description

This function stops the processing of the transferidentified by its localidentifier. The transfer request is switched according to the following rules:

initial state final state

ITP_XFER_TO_BEGIN ITP_XFER_FROZENITP_XFER_DELAYED ITP_XFER_FROZEN

ITP_XFER_PROGRESSING ITP_XFER_SUSPENDEDITP_XFER_SERVICING ITP_XFER_INTERRUPTED

The transfer request does not need to be locked to perform this operation.

Note

A suspension operation applied on a delayed transfer request switches itsstate into ITP_XFER_FROZEN.


42/154



Example

/* Description:

- suspend a transfer request corresponding to local identifier N

- resume that transfer

- suspend it once more

- cancel it

*/#include

#include ...


ItpXferIdent_t ident;char user_name[15], password[10];...

/* initialize the arguments */memset( &ident, 0, sizeof(ItpXferIdent_t));ident.local_ident = N;...

/* opening the session */if (ItpSessionOpen(user_name, password)() == -1) {printf("Open session failed. Error msg= %s\n", ItpErrMsg());exit(1);}

.../* Suspend the transfer */if ( ItpXferSuspend(&ident) == -1)

printf("Suspension failed. Error Msg=%s\n", ItpErrMsg());else

printf("Transfer suspended: id=%ld\n", ident.local_ident);

/* Resume the transfer N */if ( ItpXferResume(&ident) == -1)

printf("Restart failed. Error Msg=%s\n", ItpErrMsg());else

printf("Transfer restarted: id=%ld\n", ident.local_ident);...

/* Suspend the transfer N*/if ( ItpXferSuspend(&ident) == -1)

printf("Suspension failed. Error Msg=%s\n", ItpErrMsg());else

printf("Transfer suspended: id=%ld\n", ident.local_ident);

/* Cancel the transfer */

if ( ItpXferCancel(&ident) == -1)


43/154



printf("Cancel failed. Error Msg=%s\n", ItpErrMsg());else

printf("Transfer canceled: id=%ld\n", ident.local_ident);...


}


44/154



4.7.13. ItpXferResume

Syntax

int ItpXferResume(ItpXferIdent_t *ident)


Return value


-1 : If an error is detected. The error type is indicated in global variableErrCod. ItpErrMsg() function returns the text of the error. ErrCod


Description

This function is used to reactivate a suspended transfer or to do again aprevious transfer. The transfer is identified by its local identifier.

The transfer request must be in the following states:

- reactivate a suspended transfer:

ITP_XFER_SUSPENDEDITP_XFER_FROZEN

- do again the same transfer:

ITP_XFER_CANCELEDITP_XFER_ENDEDITP_XFER_ACKED

The request does not need to be locked to perform this operation.

Note

None.

Example

See example of paragraph "4.7.12. ItpXferSuspend".


45/154



4.7.14. ItpEnd and ItpSessionClose

Syntax

int ItpEnd(void)

int ItpSessionClose(void) supersede of ItpEnd()

Return value




Description

These functions are used to close a sessionwith the monitor and release theresources. They both have exactly the same function.The Last transfer request locked is automatically unlocked.

Note

No API primitive will be available after either of these operations.

Example

See examples supplied in the description of the other primitives.


46/154



4.7.15. ItpErrMsg

Syntax

char *ItpErrMsg()

Return value

The return value is a pointer to an Inter.Pel internal buffer containing thetext explaining the error.

Description

This function returns the error message associated to the value of ErrCod.

If an error condition is encountered, API primitives return -1 and set an errorcode in the global variable ErrCod.

Note

It is recommended to copy the content is buffer into your program space.A subsequent call to ItpErrMsg() overrides the content of the buffer.

Example

See examples supplied in the description of the other primitives.


47/154

5.EXIT FUNCTIONS C Programming Manual Page 41____________________________________________________ ______________________________________________


5.EXIT FUNCTIONS

5.1. Presentation

Inter.Pel provides a set of user exits functions. These functions are automaticallycalled at some pre-defined steps during the transfer processing. The user cancustomize the exits functions according to his own needs. This feature allows toimplement automation processing based on transfer events occurrences.

Most of exits functions are scheduled for all protocols (common exits). Inter.Pelalso provides some few exits functions dedicated to a given protocol. Protocoldedicated exits functions are scheduled only for their related protocols.

The common exits functions are written in following files:

- exituser.c : Containing transfer exits- exitndsp.c : Network connection exit functions- exitlog.c : Containing functions related to log features- exitstat.c : Containing functions related to statistics features

They can be used for checking purpose, or for post-transfer processing.

Checking exits functions are scheduled at the following transfer phases:

- Before or after the network connection- Before or after the protocol identification phase- Before the transfer request record is written in the mailbox

- Before the data sending or receiving phase- Before each print of a log message in log file- After a log file has been archived- Before formatting a statistics record- After a state file has been archived

Post-transfer exits functions (also called end of transfer exits) are scheduled afterthe termination of a file transfer, whether the transfer has been successful orcanceled.

The exits functions have following characteristics:

- They are automatically scheduled by the monitor- They execute the program added by the user if any, and return- Data structures are used to transmit transfer parameters to the functions

The exit scheduling order depends on two things (see paragraph "5.3. Transfer exitscheduling order"):

- The transfer partner side where the functions are executed: requester side(connection initiator) or server side (connection responder)

- The transfer direction: sender or responder

Inter.Pel waits for the return of an exit function before continuing its processing.


48/154



Note:A particular batch exit mechanism named "XPR exit" is also implemented. It is anoptional feature that allows Inter.Pel to automatically start a user script (or

program) when a transfer is terminated. This xpr exit is just started, and themonitor does not wait for its return to continue its processing. Furthermore, XPRruns in a separate process, independent of Inter.Pel. "xpr exit" is explained inInter.Pel 6.6 User's Guide. It will not be described in this manual.

5.2. List of exits functions

Exits functions listed below are grouped according to the nature of their use.For each function, the transfer side where it is called is indicated in italic.

5.2.1. Network connection exits

- ExitNetConnReq(in requester side)

This exit is called before an outgoing connection call. It allows to select theappropriate network process for the exchange.

- ExitNetConnRsp(in server side)

This exit is called after the reception of an incoming connection call. Itallows to select the appropriate transfer protocol for the exchange.

5.2.2. Transfer checking

- ExitBeginConnexion(in both requester and server sides)

In requester mode (connection initiator side), called before the protocolidentification phase.

In server mode (connection responder side), called after the protocolidentification phase.

- ExitBeginSend1 (in requester side)

Called before the submitted transfer request is written in the MAILBOX.

- ExitBeginReceive1 (in server side)

Called before the received transfer request is written in the MAILBOX.

- ExitBeginSend2 (in requester side)

Called before the file data sending phase.

- ExitBeginReceive2 (in server side)

Called before the file data receiving phase.


49/154



5.2.3. Post-transfer processing

- ExitEndSend (in requester side)

Called after a file has been successfully sent.

- ExitEndReceive (in server side)

Called after a file has been successfully received.

5.2.4. Inter.Pel logging activity

-ExitLogArchived

Called after the processing of log file archiving if asynchronous batchprocessing program for log archiving is not used.

-ExitLogMessage

Called before a message is written in the log file.

5.2.5. Inter.Pel statistics activity

- ExitStatArchived

Called after the processing of stat file archiving if asynchronous batchprocessing program for statistics archiving is not used.

- ExitStatMessage

Called before a statistics record is formatted and written in the Inter.Pel statfile.

5.2.6. PeSIT protocol exit function

- ExitPesitPreConnection

Called on reception of PeSIT pre-connection message. The message

contains the callers user ID and password.

- ExitPesitMsg

Called on reception of FPDU_MSG (PI 91). The message received isconverted into local machine's character set before passing to this exit.


50/154



5.2.7. ETEBAC3 exit functions

- Et3EncodeParameters

Called by ETEBAC3 client side before sending a parameter card to its bank.It is used to format the parameter card before sending it.

- Et3DecodeParameters

Called by ETEBAC3 bank side on reception of a parameter card. It is usedretrieve the values of the parameters contained in the received parametercard.

5.2.8. ODETTE exit function

- ExitOdtGetAppli

Called by ODETTE receiver side on reception of SFID FPDU. It is used toretrieve name of the Inter.Pel application object.

Exits parameters are supplied in C data structures. Although common exits use thesame structure regardless of the protocol, some of the fields have differentmeaning according the protocol used.

See "Exit appendix" section for details on the structures and parameters.

5.2.9. FTP exit function

- ExitFtpGetAppli

Called by the FTP receiver side on reception of STOR or STOU FPDU. It isused to retrieve the name of the Inter.Pel application object.

Exit parameters are supplied in C data structures. Although common exits use thesame structure regardless of the protocol, some of the fields have differentmeanings according to the protocol used.

See "Exit appendix" section for details on the structures and parameters.

5.2.10. Identification check for network client connection request

- ExitCSLogin

Called by the server of the client graphical user interface. It is used to checkthe user name and password received from the client.


51/154



5.2.11. User Access Control Exits

The user Access Control Exits is used to insert your own control algorithms or toconnect to the existing system security package for resources access validation.

They are made up of the following routines, grouped in a single C source filenamed exitsecu.c.

Note thatunless all user access control exits are in a shared library (such as DLL),you have to re-link the monitor executable (p_sup or p_sup.exe), when any ofthem is modified.

- ExitCheckUserLogin

Called when the Monitor receives a user login request. This is where youcan validate users' identification and password.

- ExitCheckUserAccess

Called by the Monitor when a user requests to access a protected resourcesuch as site, application, transfer request, log file etc. Via this routine, youcan determine precisely who can do what.

- ExitCheckFileAccess

Called by the Monitor when a user requests to send or receive a file. throughthis exit, you can grant or deny a user's access to individual files.

- ExitCheckUserLogout

Called by the Monitor when a user ends his login session.

5.2.12. User Login Parameters Exits

The user Login Parameters Exit allows you to program users' login name andpassword, so that they don't have to supply these informations on everycommands. This routine is found in a C source file named EXITCLNT.C:

- ExitLoginParam

Called by the client program when a user issues a login request.

5.2.13. Generic protocol connection Exit

The generic protocol connection exit allows you to control incoming protocolconnection and change protocol session characteristics (change rules depend on

protocol in use). This routine is found in a C source file named EXITPCNX.C

- ExitProtocolConnection

Called at each incoming protocol connection.


52/154



5.2.14. ETEBAC5 exit functions

These exit functions are only available in server mode. They are intended for thebank to check validity of the parameters issued by the requester partner and abort

the transfer if something wrong occurs.These routines are found in a C source file named ET5EXITB.C

- Et5ExitConnectInd

Called when a CONNECT fpdu is received.

- Et5ExitCreateInd

Called when a CREATE fpdu is received.

- Et5ExitSelectInd

Called when a SELECT fpdu is received.

- Et5ExitOpentInd

Called when a OPE N fpdu is received.

- Et5ExitDtfEndInd

Called when a DTF.END fpdu is received.

- Et5ExitTransEndInd

Called when a TRANS.END fpdu is received.

- Et5ExitDeselectInd

Called when a DESELECT fpdu is received.


53/154



5.3. Transfer exit scheduling order

The exit scheduling order depends on two things:

- The transfer partner side: requester or server- The transfer direction: sender or responder

Transfer mode Transfer direction Scheduling order

Requester Sender ExitBeginSend1ExitBeginConnexionExitBeginSend2ExitEndSend

Server Receiver ExitBeginConnexionExitBeginReceive1ExitBeginReceive2ExitEndReceive

Requester Receiver ExitBeginConnexionExitBeginReceive1ExitBeginReceive2ExitEndReceive

Server Sender ExitBeginSend1ExiitBeginConnexionExitBeginSend2ExitEndSend

Inter.Pel writes a log message at each execution of a transfer exit function.

Note that only common exit routines are referenced in this layout.

5.4. Using guidelines

You must keep in mind the following rules when writing your code in exitsfunctions, otherwise you may prevent Inter.Pel from running:

- Do not call an exit function from an other exit function- Do not call functions that may crash the product- Do not call an API routine from an exit function- Do not modify or delete the product's environment variables

- Check that the field is completed before using its values- As Inter.Pel waits for the return of exits functions to continue itsprocessing, you must avoid using procedures that could block exitsfunctions

The meaning of some fields depends on the protocol used. See "Exit appendix"section for details on exits parameters.


54/154



5.5. Description of exits functions

5.5.1. ExitBeginConnexion

Syntax

#include "exituser.h"int ExitBeginConnexion(ExitConn_t *exit)

See "Exit appendix"section for the full description of the structure used.

Return value

0 : Normal behavior. The transfer processing continues

-1 : Causes the failure of the connection request. The connection requestwill be re-submitted later

Description

The ExitBeginConnexionfunction is called:

- In requester (connection initiator) mode, before the protocolidentification phase

- In server (connection responder) mode, after the protocolidentification phase

The input structure ExitConn_tcontains parameters describing the remotesite.

This exit can be used to check the calling remote site.

Note

A message is written in the log before and after each call.


55/154



5.5.2. ExitBeginSend1

Syntax

#include "exituser.h"int ExitBeginSend1(ExitXfer_t *exit)


Return value


-1 : The transfer is rejected and the corresponding transfer request is

canceled

Description

The ExitBeginSend1function is called on the requester(connectioninitiator) side, before the transfer request is written in the MAILBOX.

The input structure ExitXfer_t contains the transfer request parameters.

This exit is normally used to check transfer parameters before recordingthem in the MAILBOX. Nevertheless, the user can modify parameters of the

input structure before returning. The transfer processing will continue withthe new values.

Note


Avoid modifying the parameters of the input structure, because it may causeunpredictable behavior if some inconsistencies are introduced inadvertently.


56/154



5.5.3. ExitBeginReceive1

Syntax

#include "exituser.h"int ExitBeginReceive1(ExitXfer_t *exit)


Return value



canceled

Description

The ExitBeginReceive1function is called on the server(connectionacceptor) side, before the transfer request is written in the MAILBOX.


This exit is normally used to check the received transfer parameters beforerecording them in the MAILBOX. However, the user can modify parameters

of the input structure before returning. The transfer processing will continuewith the new values.

Note


Avoid modifying the parameters of the input structure, because it may causeunpredictable behavior if some inconsistency is introduced inadvertently.


57/154



5.5.4. ExitBeginSend2

Syntax

#include "exituser.h"int ExitBeginSend2(ExitXfer_t *exit)

See "Exit appendix" section for the full description of the structure used.

Return value



canceled

Description

The ExitBeginSend2function is called on the requester side, before thedata transmission phase.


This exit is normally used to check transfer parameters such as file attributesbefore starting file data transfer. However, the user can modify parameters

of the input structure before returning. The transfer processing will continuewith the new values.

Note


Avoid modifying the parameters of the input structure, because it may causeunpredictable behavior if some inconsistencies introduced inadvertently.


58/154



5.5.5. ExitBeginReceive2

Syntax

#include "exituser.h"int ExitBeginReceive2(ExitXfer_t *exit)


Return value



canceled

Description

The ExitBeginReceive2function is called on the server side, before thedata reception phase.


This exit is normally used to check transfer parameters such as file attributesbefore starting file data transfer. Nevertheless, the user can modify

parameters of the input structure before returning. The transfer processingwill continue with the new values.

Note


Avoid modifying the parameters of the input structure, because it may causeunpredictable behavior if some inconsistencies are introduced inadvertently.


59/154



5.5.6. ExitEndSend

Syntax

#include "exituser.h"int ExitEndSend(ExitXfer_t *exit)


Return value

0 : Normal behavior. The transfer processing continuesNo other return value is allowed

Description

The ExitEndSendfunction is called on the senderside, after the transfer isterminated.


This exit is normally used to automate post-transfer processing.

Note

A message is written in the log before and after the function call.


60/154



5.5.7. ExitEndReceive

Syntax

#include "exituser.h"int ExitEndReceive(ExitXfer_t *exit)


Return value

0 : Normal behavior. The transfer processing continuesNo other return Value is allowed

Description

The ExitEndReceivefunction is called on the receiverside, after thetransfer is terminated.


This exit is normally used to automate post-transfer processing.

Note

A message is written in the log before and the function call.


61/154



5.5.8. ExitCSLogin

Syntax

#include "exituser.h"int ExitCSLogin(char * username, char * password)

Return value

1 : The user is authorized

0 : The password is not recognized. The connection request is rejected

Description

The ExitCSLoginfunction is called to check the identificationof a userwho attempts to connect to Inter.Pel from a remote client station.

The input parameters are the login name or username: usernameandpassword: password.

Note

This exit function is linked with the client station server process.


62/154



5.5.9. ExitLogArchived

Syntax

#include "exitlog.h"int ExitLogArchived(char * path_name)

Return value

0 : No other return value is implemented in this version

Description

The ExitLogArchivedfunction is called after a log file has been archived ifasynchronous batch processing program for log archiving is not used.

The input parameter path_name is the name of the file to be archived.

Note

This exit function is linked with the "SYS" process of Inter.Pel.


63/154



5.5.10. ExitLogMessage

Syntax

#include "exitlog.h"int ExitLogMessage(LogMessage *msg, char * text)


Return value

0 : No other return value is implemented in this version

Description

ExitLogMessagefunction is called before a record is written in Inter.Pel logfile.

Input parameters:

- msg : Pointer to the message descriptor- text : Pointer to the message text

The message descriptor contains the following parameters (their type is:

time_t time_stamp date of the event corresponding to themessage

char ident[20+1] message identification (example:SUP101W)

int param_count number of variable parameters in themessage(information not supplied in this version)

char *param_value[20] values of variable parameters in the message(information not supplied in this version)

This function is used to automate processing on the occurrence ofpre-selected log messages.

Note

A list of log message identifiers is supplied in "Exit appendix" section. Aexample of exit log implementation is also provided.



64/154



5.5.11. ExitStatArchived

Syntax

#include "exitstat.h"int ExitStatArchived(char * path_name)

Return value

0 : No other return value is implemented in this version.

Description

The ExitStatArchived function is called after a stat file has been archived ifasynchronous batch processing program for statistics archiving is not used.

The input parameter path_name is the name of the file to be archived.

Note



65/154



5.5.12. ExitStatMessage

Syntax

#include "exitstat.h"int ExitStatMessage(NotifXferRecord_t *param)


Return value

0 : No statistics record is to be formattedn : Statistics record format number to be formatted by Inter.Pel

Description

ExitStatMessagefunction is called before a statistics record is formattedand written in the Inter.Pel stat file.

Input parameters:

- pa

c programming manual

Documents