next up previous 264
Next: AST Memory Management and Utility Functions
Up: UNIX Command Descriptions
Previous: ast_link - Link a program with the AST library


ast_link_adam - Link an ADAM program with the AST library

Description:
This command should only be used when building Starlink ADAM programs which use the AST library, in order to generate the correct arguments to allow the ADAM ``alink'' command to link the program. The arguments generated are written to standard output but may be substituted into the ``alink'' command line in the standard UNIX way using backward quotes (see below).

By default, it is assumed that you are building an ADAM program which does not produce graphical output. However, switches are provided for linking other types of program. This command should not be used when building stand-alone (non-ADAM) programs. Use the ``ast_link'' command instead.

Invocation:
alink program.o -L/star/lib `ast_link_adam [switches]`
Examples:
alink display.o -L/star/lib `ast_link_adam -pgplot`

Links an ADAM program ``display'' which uses the standard version of PGPLOT for graphical output.
alink plotit.o -L. -L/star/lib `ast_link_adam -grf` -lgrf

Links an ADAM program ``plotit'', written in C. The ``-grf'' switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by the current version of AST. Here, this interface is supplied by means of the ``-lgrf'' library reference.
alink plotit.o -L. -L/star/lib `ast_link_adam -grf_v2.0` -lgrf

Links an ADAM program ``plotit'', written in C. The ``-grf_v2.0'' switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by version 2.0 of AST. Here, this interface is supplied by means of the ``-lgrf'' library reference.
Switches
The following switches may optionally be given to this command to modify its behaviour:

  • ``-csla'': Ignored. Provided for backward compatibility only.

  • ``-fsla'': Ignored. Provided for backward compatibility only.

  • ``-grf'': Requests that no arguments be generated to specify which 2D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new graphics system yourself and wish to provide your own arguments for linking with it. This switch differs from the other ``grf'' switches in that it assumes that your graphics module implements the complete interface required by the current version of AST. If future versions of AST introduce new functions to the graphics interface, this switch will cause ``unresolved symbol'' errors to occur during linking, warning you that you need to implement new functions in your graphics module. To avoid such errors, you can use one of the other, version-specific, switches in place of the ``-grf'' switch, but these will cause run-time errors to be reported if any AST function is invoked which requires facilities not in the implemented interface.

  • ``-grf_v2.0'': This switch is equivalent to the ``-mygrf'' switch. It indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V2.0 of AST.

  • ``-grf_v3.2'': Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V3.2 of AST.

  • ``-grf_v5.6'': Indicates that you want to link with your own graphics module which implements the 2D graphics interface required by V5.6 of AST.

  • ``-myerr'': Requests that no arguments be generated to specify how error messages produced by the AST library should be delivered. You should use this option only if you have implemented an interface to a new error delivery system yourself and wish to provide your own arguments for linking with it. By default, error messages are delivered in the standard ADAM way via the EMS Error Message Service (Starlink System Note SSN/4).

  • ``-mygrf'': This switch has been superceeded by the ``-grf'' switch, but is retained in order to allow applications to be linked with a graphics module which implements the interface used by AST V2.0. It is equivalent to the ``-grf_v2.0'' switch.

  • ``-pgp'': Requests that the program be linked so that 2D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output.

  • ``-pgplot'': Requests that the program be linked so that 2D graphical output from the AST library is displayed via the standard (or ``native'') version of the PGPLOT graphics package. By default, no graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output.

  • ``-grf3d'': Requests that no arguments be generated to specify which 3D graphics system is used to display output from the AST library. You should use this option only if you have implemented an interface to a new 3D graphics system yourself and wish to provide your own arguments for linking with it.

  • ``-pgp3d'': Requests that the program be linked so that 3D graphical output from the AST library is displayed via the Starlink version of the PGPLOT graphics package (which uses GKS for its output). By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output.

  • ``-pgplot3d'': Requests that the program be linked so that 3D graphical output from the AST library is displayed via the standard (or ``native'') version of the PGPLOT graphics package. By default, no 3D graphics package is linked and this will result in an error at run time if AST routines are invoked that attempt to generate graphical output.
SLALIB
The AST distribution includes a cut down subset of the C version of the SLALIB library written by Pat Wallace. This subset contains only the functions needed by the AST library. It is built as part of the process of building AST and is distributed under GPL (and is thus compatible with the AST license). Previous version of this script allowed AST applications to be linked against external SLALIB libraries (either Fortran or C) rather than the internal version. The current version of this script does not provide this option, and always uses the internal SLALIB library. However, for backward compatibility, this script still allows the "-fsla" and "-csla" flags (previously used for selecting which version of SLALIB to use) to be specified, but they will be ignored.



next up previous 264
Next: AST Memory Management and Utility Functions
Up: UNIX Command Descriptions
Previous: ast_link - Link a program with the AST library

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
7th December 2012
E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2012 Science \& Technology Facilities Council