Calling concepts

You only need to read this section if you are calling the API directly from a language such as C or COBOL, and are not using one of the supplied wrappers.

Passing parameters

The Bank Wizard API has been designed so that it can be cross called from many different languages, such as C, COBOL and Perl. There are two basic ways that computer languages pass parameters to subroutines:

Pass by address – the memory address of a variable is passed to the subroutine. Since the subroutine has the variable's address it can change the variable value in the calling subroutine. This scheme is used by COBOL
Pass by value – a copy of the value is passed to the subroutine. Therefore the subroutine cannot change the value in the calling subroutine. This scheme is used by C

If you want a C subroutine to change the value of a variable, you pass the address of the variable. This allows some variables to be passed by value and some by address.

So that the Bank Wizard core can be called from as many languages as possible, the main API takes all parameters as addresses.

Passing strings

You use BWISetString to store various strings within the handle. To use this function, you must specify the string type being set, the string and the string length (the number of characters to be stored in the handle). Each country has symbolic constants used to name the strings, such as BWI_UK_SORT_CODE and BWI_UK_ACCOUNT_NO. Therefore a typical call to set a string would be:

BWISetString(h,BWI_UK_SORT_CODE,"010004",6);

When calling from C, use the wrapper BWICSetString:

BWICSetString(h,BWI_UK_SORT_CODE,010004);

In this case, you do not need to pass the length because C strings typically end with a hidden character (null or 0 byte). The length is determined by counting characters until the null is found.

BWICSetString is implemented as follows:

BWICSetString(BWI_HANDLE* h,long item, char* string)

{

long len = strlen(string);

BWISetString(h,&item,string,&len);

}

Recovering strings

You use BWIGetString to recover strings from the handle. For example, you can retrieve transposed account details or branch address details. Recovered strings are always terminated with the C style null character. (Languages other than

When calling BWIGetString you must tell Bank Wizard how many characters are available in the string variable that you pass to it. This prevents the possibility of Bank Wizard overwriting memory outside of the string, which could cause program instability or a crash. Bank Wizard tells you how many characters are required to store the string so that you can detect if you are passing a buffer that is not long enough for the entire string. If the returned length value is greater than the value you passed, then the data has been truncated.

Because there is always a trailing null, one fewer character will be returned.

In this example, str cannot contain more than 5 actual characters and a terminating null.

size is set to the actual number of characters. Therefore, str could not deal with a UK account number, which is typically 8 characters long. For an 8 character account number, size is returned as 9 (8 characters + the terminating null).

char str[6];

long size = sizeof(str);

BWIGetString(h,BWI_UK_ACCOUNT_NO,str,size);