Documentation:Reference:Fortran - MdsWiki
Navigation
Personal tools

From MdsWiki

Jump to: navigation, search

Variable length argument lists

The following mdslib functions accept variable length argument lists:

For all these functions, the variable length argument list MUST be terminated by the integer value 0 passed by reference. In fortran, this means:

result = function(arg1, arg2, ..., argN, 0)

whereas in C this means:

int null = 0;
int status = function(arg1, arg2, ..., argN, &null);

Note that there may be arguments before or after the variable length argument list. In this case (for fortran):

result = function(expression, arg1, arg2, ..., argN, 0, length)

descr / descr2

int descr(int *data_type, void *data, [int *dim1, int *dim2, ..., int *dimN], NULL, [int *length])
int descr2(int *data_type, [int *dim1, int *dim2, ..., int *dimN], NULL, [int *length])

The descr function returns a descriptor number for use in MdsValue and MdsPut. The descr2 function returns a descriptor number for use in MdsValue2 and MdsPut2. These routines have a variable length argument list. Note that there are a maximum of 256 descriptors available for use at any one time. This is because the descriptor numbers are indices into a global struct descriptor array with 256 elements. If a 257th descriptor is requested, the 1st descriptor will be freed and reassigned. If creating a descriptor for a scalar, do not specify any dimN. Just use NULL:

idesc = descr(IDTYPE_FLOAT, scalar, 0)
idesc = descr2(IDTYPE_FLOAT, 0)
idesc = descr(IDTYPE_FLOAT, array, npts, 0)
idesc = descr2(IDTYPE_FLOAT, npts, 0)
idesc = descr(IDTYPE_FLOAT, array, n1d, n2d, 0)
idesc = descr2(IDTYPE_FLOAT, n1d, n2d, 0)

Creating a descriptor for a string (length = space allocated for the string):

character string*length
idesc = descr(IDTYPE_CSTRING, string, 0, length) idesc = descr2(IDTYPE_CSTRING, 0, length)

Creating a descriptor for a string array (length = space allocated for the string, npts = number of elements in array):

character*length string(npts)
idesc = descr(IDTYPE_CSTRING, string, npts, 0, length) idesc = descr2(IDTYPE_CSTRING, npts, 0, length)

A complete list of the data types is in MDSLIB.INC

MdsClose

int MdsClose(char *tree, int *shot)

Close connection to a tree. Note that shot is passed by reference. Return value is status: odd if ok, even if error.

MdsConnect

SOCKET MdsConnect(char *host)

Establishes a socket connection to remote MDSplus server at host. To connect to a specific port number, host should look like birch.pppl.gov:8501 SOCKET is defined in $MDSPLUS/include/ipdesc.h as an int for unix. The return value is the socket number, or INVALID_SOCKET if there is a problem. INVALID_SOCKET is defined in $MDSPLUS/mdstcpip/mdsip.h as -1. If the system is currently connected to a socket when MdsConnect is called, MdsConnect will first disconnect from that socket.

MdsDisconnect

void MdsDisconnect()

Disconnect from currently connected socket. As this socket is stored as a global variable, there is no need to pass the socket number as an argument.

MdsOpen

int MdsOpen(char *tree, int *shot)

Open connection to a tree. Note that shot is passed by reference. Return value is status: odd if ok, even if error.

MdsPut / MdsPut2

int MdsPut(char *node, char *expression, [int *descr1, int *descr2, ... int *descrN], NULL)
int MdsPut2(char *node, char *expression, [int *descr1, void *data1, int *descr2, void *data2,
            ... int *descrN, void *dataN], NULL)

Put expression into tree in node reference node. If expression contains parameter place-holders ($), pass in a descriptor number for each parameter. This is a variable length argument list. Note that there are a [#descr / descr2|maximum] of 256 descriptor arguments that can be passed in the variable length argument list. Return value is status: odd if ok, even if error. In fortran:

   status = MdsPut("SOMENODE","BUILD_SIGNAL(BUILD_WITH_UNITS($,$),,$)",
*                  descr(IDTYPE_FLOAT,dataarray,npts,0), 
*                  descr(IDTYPE_CSTRING,"units",0), 
*                  descr(IDTYPE_FLOAT,dim0array,npts,0),0)
   status = MdsPut2("SOMENODE","BUILD_SIGNAL(BUILD_WITH_UNITS($,$),,$)",
*                  descr2(IDTYPE_FLOAT,npts,0),dataarray, 
*                  descr2(IDTYPE_CSTRING,0),"units", 
*                  descr2(IDTYPE_FLOAT,npts,0),dim0array,0)

The difference between MdsPut and MdsPut2 is that in the MdsPut2 call the user variables are arguments to the MdsPut2 call instead of arguments to the descr call. The original descr function was implemented to build an internal data structure which completely described the user's variable including the memory address of the data. Unfortunately the optimizers in some compilers and utilities may change the location of a variable between the call to descr and MdsPut invalidating the memory address saved during the descr call. Passing the user's variable in the the call to MdsPut2 is much safer and should work in all environments. Use the descr2 function when using MdsPut2.

Note that the length argument was not needed on the string descriptor as the string is being passed in already known.

MdsSetDefault

int MdsSetDefault(char *node)

Change the default node to node. Return value is status: odd if ok, even if error.

MdsValue / MdsValue2

int MdsValue(char *expression, [int *descr1, int *descr2, ... int *descrN],
             int *descrAnswer, NULL, [int *length])
int MdsValue2(char *expression, [int *descr1, void *data1, int *descr2, void *data2, ... 
              int *descrN, void *dataN],int *descrAnswer, void *answer, NULL, [int *length])

Returns the value of expression in the descriptor descrAnswer. The value is converted to the type of descrAnswer and fit within descrAnswer's size

If there are parameter place-holders in expression ($), pass in a descriptor number for each parameter. This is a variable length argument list. Note that descrAnswer is considered to be part of the variable length argument list (as it comes before NULL), so there is always at least one argument in the list --- a return descriptor descrAnswer is required as the means of passing back the value of expression. There is therefore a limit of 255 descriptor numbers available for passing in parameters. length will contain the number of elements in the resulting value of expression (1 if scalar), or the number of characters if the the result is a DTYPE_CSTRING. If the result is a string array, length will be the number of elements.

This parameter is optional. However, if it is not desired, it is still necessary to reserve a place for it by adding an extra comma in fortran:

real result
status = MdsValue("1",descr(IDTYPE_FLOAT,result,0),0,)

or

status = MdsValue2("1.",descr2(IDTYPE_FLOAT,0),result,0,)

Note: modern compilers may require '-fugly-comma' flag to support this.

Further Note: some off site documentation recommended passing the value 1 by reference if the return length is not wanted. This is an error which will on some platforms cause a segfault. A new library libMdsFLib that replaces libMdsLib supports this convention of '1' by reference, and be used for programs that can be relinked but not re-compiled

If the length is desired, then call MdsValue as follows:

real result
int length
status = MdsValue("1",descr(IDTYPE_FLOAT,result,0),0,length)

or

status = MdsValue2("1.", descr2(IDTYPE_FLOAT,0),result,0,length)

The difference between MdsValue and MdsValue2 is that in the MdsValue2 call the user variables are arguments to the MdsValue2 call instead of arguments to the descr call. The original descr function was implemented to build an internal data structure which completely described the user's variable including the memory address of the data. Unfortunately the optimizers in some compilers and utilities may change the location of a variable between the call to descr and MdsValue invalidating the memory address saved during the descr call. Passing the user's variable in the the call to MdsValue2 is much safer and should work in all environments. Use the descr2 function when using MdsValue2.

Return value of MdsValue/MdsValue2 is status: odd if ok, even if error.