Description

The libdcs-33.a DCS 3.3 compatibility library provides Fortran and C language access to most of the DCS commands. Individual routines are provided for the commands listed in the table below. Replace the dcs_name string (as noted in the synopsis above) with the actual DCS command name.

The status parameter is a pointer to a 32-bit int (for C users) or a 32-bit INTEGER variable (INTEGER*4, for Fortran users) that will contain the exit status of the command.

The options parameter is a string to be parsed into command arguments passed to the DCS command. For C programs, specify either a C character string, or a string constant. For Fortran users, pass either a character constant or a CHARACTER variable. There is no need for Fortran users to add a zero (NUL) byte to options parameter to signal the end of the string.

The parsing of the options parameter proceeds as follows:

The output parameter will contain both the standard output (stdout) and standard error (stderr) (concatenated together in that order) from the DCS command. For C users, this a buffer will be dynamically allocated to contain the returned text (with a limit of 2 million bytes), and output will be set to point to this buffer. The application must free this buffer when it no longer requires it, or a memory leak will result. For Fortran users, pass a CHARACTER variable large enough to contain the expected output. If the CHARACTER variable is not large enough to contain the output, the output will be truncated to fit within the allotted space. If the declared CHARACTER variable is larger than the output, the CHARACTER variable will be blank padded to the size of the variable.

Return Values

Errors

If -1 is returned, errno will likely have been set by one of the following library or system calls: close(2), dup2(2), fork(2), free(3), malloc(3), pipe(2), read(2), select(2), and waitpid(2).

Notes

The library routines work by executing a fork(2) to create a child process, then execvp(2) to start the DCS command (which searchs along the PATH environment variable to find them). The stdout and stderr streams are collected by reading two pipes and placing the output either into the appropriate user-provided buffers or allocating and returning new buffers. The child process is reaped with waitpid(2).

Ensure your PATH includes the directory containing the DCS commands.

Since the mscdsetup command is not supported by this interface, either provide absolute MSS pathnames, or execute the appropriate mscdsetup(1NCAR) and mscd(1NCAR) commands prior to invoking your application.

The Fortran bindings are only available as subroutines, do not declare or attempt to use these routines as Fortran functions. No Fortran include file is provided.

AIX FORTRAN WARNING: The AIX Fortran compilers do not automatically suffix external symbol names with an underscore character (_) as is done by the compilers for other operating systems. This means you must do one of two things:

Examples

Here is a C example of msls:

#include <dcs-33.h>

int
main(int argc, char** argv)
{
	int     status;
	char    *options;
	char    *output.

	options = "-l";
	msls(&status, options, &output);
	printf("%d\n", status);
	printf("%s\n", output);
	free(output);
	return(0);
}

Here is a Fortran example of msls:

    PROGRAM TST

    CHARACTER*80    options
    CHARACTER*1024  output
    INTEGER         status

    options = "-l"
    CALL MSLS(status, options, output)
    PRINT *, status
    PRINT '(A)', output
    END

Here is a more complex example of using the asynchronous feature of msrcp. In this example, we submit the msrcp request, then perform some other tasks, then wait for the msrcp request to complete. Be sure you review the msrcp man page for a complete description of using the "-async" option.

    PROGRAM TST

    CHARACTER*80    options
    CHARACTER*1024  output
    INTEGER         status

C   (...create local file "foo"...)
C  The DCS job id is placed into "output".

    options = "-async foo mss:/LOGIN/foo"
    CALL MSRCP(status, options, output)
    IF (status .NE. 0) THEN
      PRINT *, "msrcp failed: msrcp ", options
      STOP
    ENDIF

C Perform other tasks.
C Now wait for the msrcp to complete...

    options = output
    CALL DCSWAIT(status, options, output)
    END

Files

These routines are located in the /usr/local/dcs-4.0/lib32/libdcs-33.a file for 32-bit API programs, the /usr/local/dcs-4.0/lib64/libdcs-33.a file for 64-bit API programs, possibly also with symlinks in other system specific locations.

See Also

DCS C/C++ Library and DCS Fortran 90/95 Library

dcsjlog(1NCAR), dcsq(1NCAR), dcsrm(1NCAR), dcswait(1NCAR), msallinfo(1NCAR), mschproj(1NCAR), msclass(1NCAR), mscomment(1NCAR), msdu(1NCAR), msfind(1NCAR), msls(1NCAR), msmv(1NCAR), mspasswd(1NCAR), msrawinfo(1NCAR), msrcp(1NCAR), msrecover(1NCAR), msretention(1NCAR), msrm(1NCAR), mstouch(1NCAR).

Copyright

2008 University Corporation for Atmospheric Research, all rights reserved.