Home

page 85 - Legion - University of Virginia

1. define LEGION_NO_ERROR 0 define LEGION NOT A LOID 1 define LEGION NOT IN CONTEXT SPACE 2 define LEGION UNKNOWN ERROR 3 define LEGION CONTEXT SPACE INVALID 4 define LEGION ROOT CONTEXT ALREADY EXISTS 5 define LEGION CONTEXT ALREADY EXISTS 6 define LEGION NO CONTEXT CLASS 7 define LEGION CONTEXT CREATE FAILED 8 define LEGIO UNABLE O ADD PATH 9 define LEGIO THOD_TIMED_OUT 10 define LEGION_BAD_ATTRIBUTE_FORMAT d define LEGION UNABLE TO GET INTERFACE 12 define LEGION PARM ALREADY EXISTS 13 define LEGIO PARM DOES NO EXIS 14 define LEGION PARM WRONG TYPE 15 define LEGION PARM NO DATA 16 define LEGIO PARM UNABLE O_REPLACE 17 define LEGION_NOT_A_CLASS 18 define LEGION_NOT_A_HOS 19 define LEGION NOT A VAULT 20 define LEGION NOT AN IMPL 21 define LOID NOT EXPECTED 22 define LOID EXPECTED 23 define LEGION PARM TYPE UNKNOWN 24 define LEGION OUTCALL FAILED 25 define LEGION OUTCALL PERMISSION DENIED 26 define LEGION CLASS NOT FOUND 27 define LEGION_BAD_ARGUMENT 28 define LEGION_OBJECT_TYPE 29 define LEGION_NO_CURRENT_CONTEXT 30 define LEGION_OBJECT_NOT_FOUND 31 define LEGION INTERNAL ERROR 32 define LEGION EMPTY LOID 33
2. cc cece ns 152 9 5 LEGION attributes J 3 5A courte hk S Ede EE ES tS 168 8 6 Interfaces to Legion objects 25 2 ioo dia va oven vae btt ta 175 8 7 Legion C type manipulation 0 0 ccc enn 176 8 8 Legion hostob ett iss cpu eR enna epeRxg asa ekY tases 180 8 9 VaultobIBOls su tes EAE ERR SERES RE RENI ERE BM 185 8 10 Class OIC p fe cate dao d Signe pawn hanes dido T4 ad 189 8 11 Legion implicit parameters 0 0 cece ee ees 191 8 12 Collections s hic pere oceteltd sra qe dane cae dee eie eu 198 9 0 Error messages 202 Getting help 203 Index 204 page 4 Reference J une 19 2001 Legion 1 7 Reference Manual Before you start 1 0 Introduction 1 1 Aboutthis manual This manual provides detailed information about specific parts of the Legion system It is intended to be a supplementto the other Legion documentation and new users are advised to start with the Basic User Manual There are four Legion manuals each aimed ata specific type of user that can be consulted for more information The others are Basic User Manual introductory information about the system System Administrator Manual information and documentation for administrators of Legion systems including installing and running Legion configuring security features resource management and managing a Legion system Developer Manual information and documentation for programmers working in Legion and includes information o
3. set_collection c debug help l scheduler LOID gt collection path 1 collection LOID gt This command can be used to query or configure the helper objects used by a basic Legion scheduler Basic Legion scheduler objects use a collection helper object to obtain information about available resources upon which they can schedule objects After constructing a schedule basic Legion schedulers use an enactor helper object to implement scheduling decisions to actually start up the scheduled objects Use this command to assign a particular collection and enactor to a basic Legion scheduler or vice versa The following optional parameters are supported get enactor get collection set enactor set collection debug help legion_host_vault_list c host context path 1 host LOID gt ae pos debug t vaultl vault2 help Print the LOID of a basic Legion scheduler s currently assigned enactor helper object Print the LOID of a basic Legion scheduler s currently assigned collection helper object Setthe enactor named in enactor LOID or enactor path to the scheduler Set the collection named in collection LOID Or collection path to the scheduler Catch and print Legion exceptions Print command syntax and exit vaultn p Usedto display and manipulate listof vaults with which the hostnamed in host cont
4. available The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_set_scheduler c lt class context name 1 class LOID gt c Scheduler context path 1 Scheduler LOID gt debug help This commands sets the scheduler named in scheduler LOID Or scheduler context path forthe class named in c1ass LOID Or class context path This will be the default scheduler for that class The class will then use the scheduler to determine which hosts and vaults should manage its instances i e determine placements for the class s instances The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_set_scheduler_policy c lt class context name gt 1 class LOID gt policy debug page 54 help This command can be used to seta class object s policy for using its default scheduler See also 1egion set scheduler The legal values for policy are 0 This policy value specifies that the class named in class LOID or class context path should use its default scheduler if the scheduler is currently active It is intended to protect bootstrap classes which may be involved in activating schedulers and scheduler helper objects Typically this policy is not recommended for user class objects Classes using this policy should have a defau
5. lt hostn gt p debug help page 48 Manipulates the listofacceptable hosts upon which the instance can be placed Note that if you use identify the instance by its context path you must use context paths in the hosti host2 hostn parameter Conversely if you identify the instance by its LOID with the 1 flag you must use LOIDs in the nost 1 host2 hostn parameter The following optional parameters are supported 1 Use LOIDs to specify instance and host a Add named host to the instance s acceptable host list d Delete named host from the instance s acceptable host list t Test whether or not a host is on the instance s acceptable host list p Display the instance s acceptable host list debug Catch and print Legion exceptions help Print command syntax and exit Youcanusethe a a and t flags more than once when running the command but regardless of how you list them on the command line Reference June 19 2001 Legion 1 7 Reference Manual Legion will process themin a specific orderwhen you run the command first adding any new hosts then deleting old hosts then testing any hosts and finally printing outthe results legion instance vault list c instance context name gt 1 instance LOID gt a d t vaulti lt vault2 gt lt vaultn gt p debug help Manipulates the list of acceptable vaults upon which the instance can
6. help legion output state c object context name 1 object LOID gt StartupState debug help Registers the given binary named in binary path as a stateful stateless or sequential Mentat object for the architecture named in arch and under the class object named in lt class name gt This command is automatically run when you use the 1egion mplc command without the nolegion option to compile an MPL program In the example below MentatObject is a stateful Mentatobjectin the local path home legion binona 1inuxOralpha linux machine To register it as belonging to a class with the context path name ClassObject MentatObject in linux or alpha linux architectures you would enter legion mplc reg impl ClassDirectory MentatObject home legion bin MentatObject stateful linux or legion mplc reg impl ClassDirectory MentatObject home legion bin MentlatObject stateful alpha linux The following option is supported help Print command syntax and exit This command uses a special output device for debugging and information reporting When output is sent using this mechanism the object s will decide whetherthattype of information is to be displayed and where to display it Users will be given a series of options to selectively filter what output is displayed to the screen The output levels include Warnings Information e Low Level Debug High Level Debug Errors
7. v Run in verbose mode debug Catch and print Legion exceptions help Print command syntax and exit legion_destroy_vault c vault context path 1 vault LOID gt debug help legion initialize Destroy a given vaultobject Legion will attemptto move allofthe vault s current OPRs off of the vault object and then destroy the vault object If any OPRs cannot be successfully moved the process will abort and an error message will be displayed The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit P opulates the Legion system with basic classes and implementations This command should be run aftera Legion system is started forthe first time using legion_startup On subsequent activations of the system the state created by this utility will already exist so this command should not be run again Reference page 39 June 19 2001 Legion 1 7 Reference Manual legion list host accounts l host object LOID gt c host object context path debug help user id This command is used on PCD host objects It lists the available accounts on a hostobject If no hostobject argumentis provided your current host object will be used as a default The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion make setup script o lt script basename gt OPR lt OPR dir nam
8. 8 9 Vault object The following section contains functions which are used to make calls directly on host objects CLegionVaultReservation MakeReservationFromVault LegionidType VidType char VaultName LegionldType HlaType char ReqHostNm Ask a vault to make a reservation for either an instantiation or an activation Parameters Reference page 185 J une 19 2001 Legion 1 7 Reference Manual VidType A flag indicating whether VaultName is a context path name or a LOID VaultName The name of the vault that will make the reservation HIdType A flag indicating whether RegHostName is a context path name or a LOID RegHostName The name of the host to be paired up with this vault reservation Return Values The CLegionVaultReservation that represents the VaultR eservation just made Error Return 0 User Responsibility Useris responsible for destroying the vaultreservation when done CLegionVaultReservationRecord CheckVaultReservation LegionldType VidType char VaultName CLegionVaultReservation VtRes Check on the status of a vault reservation previously made Parameters HIdType A flag indicating whether VaultName is a context path name or a LOID VaultName The name of the vault that will check the reservation VtRes The Vault reservation previously made Return Values A CLegionVaultR eservationR ecord containing the status of the reservation Error Return 0 User Responsibility User
9. in context path Copy the specified Legion file to the cur rent working directory of the remote program out context path Copy the specified Legion file s con tents outofthe currentworking directory of the remote program into Legion con text space The remote object s path should be the same as the context path IN lt local file name gt Send the specified local file to the cur rent working directory of the remote program OUT local file name Copy a file out of the current working directory of the remote program into the specified path in your local file system f options file Obtain options from the specified file An options file can contain one or more legion nq flags delimited by spaces Reference June 19 2001 novrun t minutes n nodes r lt minutes gt p priority q context path d lt argl gt lt arg2 gt lt argn gt Reference Legion 1 7 Reference Manual tabs or newlines An options file is especially useful if your program uses several in out or IN OUT flags You can include any flags but not arbi trary command line arguments Disable use ofthe virtual architecture on virtual hosts The remote program will run on the physical architecture for the selected host This option is not usually appropriate for user tasks WARNING the registered implementation for the virtual architecture of the selected host should also be usable o
10. A List all known context aliases for each listed object d List contexts like other objects rather than listing their contents q When creating a long list do notactivate inactive objects v Run command in verbose mode debug Catch and print Legion exceptions help Print command syntax and exit Creates a new contextin Legion contextspace and assigns itthe name given in lt context path gt This command is analogous to the Unix mkdircommand itis also identicaltothe 1egion context create command The new context will be placed in your current context The output will contain the new context s location and its LOID The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Reference page 33 J une 19 2001 legion mv Legion 1 7 Reference Manual context path new context path debug legion pwd debug legion rm pSET West debug page 34 help help Assigns a new context name given in new context path to the object named in context path Pathnames can be relative or absolute Analogous to the Unix mv command The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Prints your current context path Similar to the Unix pwa command The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit
11. represent all of the x necessary C classes that 7 would normally be used in Ea A their place In all cases R these are actually pointers xy to LRefs to the actual xf class type This double xf level of pointer ef indirection was done to x allow for some small measure f of reference counting Rj page 141 J une 19 2001 Legion 1 7 Reference Manual The following section contains all of the valid Legion architectures define LEGION ARCH linux 1 define LEGION_ARCH_solaris 2 define LEGION_ARCH_sun4 3 define LEGION ARCH alpha linux 4 define LEGION ARCH alpha DEC 5 define LEGION ARCH sgi 6 define LEGION ARCH rs6000 7 define LEGION ARCH hp 8 define LEGION ARCH t90 9 define LEGION ARCH c90 10 define LEGION ARCH t3e d define LEGION ARCH x86 freebsd 12 define LEGION ARCH winnt x86 t3 All programs that use the CLegionLib library contain some small amount of state which determines how the CLegionLib library interacts with certain Legion functions The following section gives the declarations for the functions that allow the user to interface with this state void SetTimeOutValue int Seconds These functions set and clear void ClearTimeOutValue 0 the default timeout value for most Legion method invocations Rif void SetForceActivation tye In some small number of calls void ClearForceActivation 0
12. Parameters CldType A flag indicating whether ClassName is a LOID or a context path ClassName The name ofthe class to activate the instance for CInfo A CInstanceP lacementinfo variable indicating which instance to activate and where Return Values 1 on Success 0 on Failure User Responsibility None int Deactivatelnstance egionldType ClaType char ClassName LegionldType OldType char ObjName Asks a class to deactivate one of its instances Parameters CldType A flag indicating whether ClassName is a LOID ora context path ClassName The name of the class to deactivate the instance for OldType A flag indicating whether ObjName is a LOID ora context path ObjName A LOID or context path indicating which object to deactivate Return Values 1 on Success 0 on Failure User Responsibility None int ForcedDeactivatelnstance LegionldType CldType char ClassName LegionldType OldType char ObjName Asks a class to deactivate one of its instances If the objectis in the going up state or in the going down state this call will fail Parameters CldType A flag indicating whether ClassName is a LOID or a context path page 190 Reference J une 19 2001 Legion 1 7 Reference Manual ClassName The name ofthe class whose instance is to be deactivated OldType A flag indicating whether ObjName is a LOID ora context path ObjName A LOID or context path indicating which object to deactiv
13. Reference page 91 June 19 2001 legion_native_mpi_run v a lt architecture gt IN local input file gt in Legion input file gt n lt nodes gt t help debug program context page 92 Legion 1 7 Reference Manual minutes legion path arg 1 arg 2 gt Start a native MPI program h host context path gt OUT local result file gt out Legion result file gt arg n The following parameters are used for this command h host context path v a architecture IN lt local input file gt OUT local result file gt in Legion input file Specify the host on which the program will run The default setting is the system s default placement which is to pick a compatible host and try to run the object If the host fails the system will try another compatible host Verbose option S pecify the architecture to run on S pecify an input file that should be copied to the remote run from the local file system S pecify a result file that should be copied back from the remote run to the local file system S pecify an input file that should be copied to the remote run from the Legion context space out Legion result file Specify a result file that should be n nodes t minutes legion help debug argl lt arg2 gt lt argn gt Reference copied out from the remote run into Legi
14. a target Legion object may not 7 not yet be active The forc Ej activation flag indicates f whether the call should xy activate the object or fail All programs that use the CLegionLib library contain some small amount of state which determines how the CLegionLib library interacts with certain Legion functions The following section gives the declarations for the functions that allow the user to interface with this state page 142 Reference J une 19 2001 Legion 1 7 Reference Manual 8 1 Legion Library interface The following section lists the functions which interface with the C Legion Library int Legion init Initializes the legion library for a Legion object started by a Legion host not for a command line object This function or one of the other init functions must be called in all Legion programs before any other Legion calls are made This does not preclude calls to the CLegionLib which do not directly interact with Legion Parameters None Return Values 1 on Success 0 on Failure User Responsibility None int Legion_init_with_class char ClassID int ClassidLen Initializes the Legion library for a Legion object started as an instance of a certain Legion class but perhaps started on the user s command line This function or one of the other init functions mustbe called in all Legion programs before any other Legion calls are made This does not preclude calls to the CLegionLib w
15. expand and to be filled with NULL bytes Seeking to negative logical positions the buffer does not cause the buffer to expand the buffer pointer is placed at logical position 0 size t size Parameters None Returns the current size of the buffer in bytes size t current byte Parameters None Returns the number of the byte to which the buffer pointer currently points Current byte returns 0 when the buffer pointer is at the beginning of the buffer and current byte size when the buffer pointer is at the end of the buffer char linearize Parameters int pack_metadata 0 Returns a pointer to the beginning of the buffer s data This pointer is guaranteed to point to data that is contiguous in memory Depending on the implementation of the LegionStorage this function may or may not need to return a pointer to a copy of the data void setMetaData Parameters LegionMetaData md Sets the metadata associated with the LegionStorage LegionMetaData getMetaData Parameters None Returns the meta data associated with the LegionStorage This is useful for instantiating an appropriate LegionBuffer based on a given LegionStorage 7 4 3 Operations on the associated LegionP acker A LegionPacker exports operations for packing and unpacking the basic C data types into and out of a LegionBuf fer in a particular data format A LegionPacker exports put 2Zz and get ZZzZ forall zzz in char short ushort int long ulo
16. DeleteObject LegionidType IdType char ObjName Deletes or Destroys a given object by asking its class to get destroy it This function is identical to DestroyO bject Parameters IdType Flag indicating whether parameter is a LOID or a context path name Name Either the context path name or the LOID of the object to delete Return Values 1 on Success 0 on Failure User Responsibility None int DestroyObject LegionldType IdType char ObjName Deletes or Destroys a given object by asking its class to get destroy it This function is identical to DeleteO bject Parameters IdType Flag indicating whether parameter is a LOID ora context path name Name Either the context path name or the LOID of the object to destroy Return Values 1 on Success 0 on Failure User Responsibility None int DeactivateObject LegionldType IdType char ObjName Deactivates a given object Parameters IdType Flag indicating whether parameter is a LOID ora context path name Name Either the context path name or the LOID of the object to deactivate page 162 Reference J une 19 2001 Legion 1 7 Reference Manual Return Values 1 on Success 0 on Failure User Responsibility None int ForcedDeactivateObject LegionldType IdType char ObjName Deactivates a given object The forced in this call means that if the object is going up or going down then an error is returned Parameters IdType Flag indicating whet
17. Fatal Errors Reference page 75 June 19 2001 legion record uf local storage file name gt c recorder context path name debug session name gt t lt interval gt client application lt argl gt lt arg2 gt lt argN gt debug page 76 help Legion 1 7 Reference Manual There are two ways to use this command Y ou can dynamically change which of a specified object s outputtypes are filtered outand which are displayed This option also allows the userto change the location ofthe output from stderr stdout and any Unix file they want Or you can use the StartupState option in which case the command will print instructions for bringing up a new system with the desired output state Please note if you use StartupState legion output state does not contact Legion and therefore does not run as a Legion program l e you can execute it outside of a running Legion system Otherwise it runs as a normal Legion command line tool The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Executes the application named in lt client application gt inrecord mode so thatitcan later be played back with the legion_replay tool All objects started by the application will record all relevant event activity in a local file named in lt local storage file name gt orina previously started Legion recorder object named in recorder context
18. Like the legion_make command this tars the current directory copies itto a remote host untars it and executes a make command on it The resulting compiled binaries can be registered with Legion via the directory s makefile Optional flags let you specify different architectures and make commands The following options are supported v Verbose mode Print actions as command executes a architecture S pecify an architecture on which to run make This option can be specified multiple times to request concurrent builds on multiple platforms If no architectures are specified a remote make for the current architecture LEGION ARCH is performed e make command Specify the make command for the remote build default is make argl arg2 argn These optional arguments are passed to the remote make command They can specify make targets or other build parameters debug Catch and print Legion exceptions help Print command syntax and exit Reference J une 19 2001 legion mplc lt flags gt legion_mplc_reg_impl Legion 1 7 Reference Manual Compiles MPL MentatP rogramming Language programs There are several possible parameters to this command please see the MPL Manual for more information the MPL Manual is available from the Legion web site at lt http legion virginia edu documentation htmI gt lt class name gt lt binary path gt lt stateless stateful sequential gt lt arch gt
19. Please see section 14 0 in the System Administrator Manual page 24 Reference June 19 2001 legion list domains Legion 1 7 Reference Manual Creating an implementation BindingAgent for BindingAgentClass Creating an implementation BasicFileObject for BasicFileClass Creating an implementation ttyObject for ttyObjectClass Creating an implementation StatTreeObject for StatTreeClass The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit debug help Listthe domains currently connected to yourcurrentLegion domain The output will list the binding for your current domain and any domains linked to your current domain Please see legion_combine_domains page 22 for information about connecting Legion domains The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_print_domain_cookie i cookie input file gt debug help Displays the contents ofa Legion domain cookie file required for using legion combine domains By default the command displays the contents of the file LegionDomainCookie lt current domain id but any input file name can be specified using the i option The following options are supported i lt cookie input file gt Specify the path of the cookie file to print debug Catch and print Legion exceptions help Print command syntax and exit
20. UVaL_Reference lt LegionBuffer gt return lb return lb new LegionBuffer return lb put int amp result 1 Legion return UVaL METHOD RETURN VALUE wu get continuation list return 1b wrapper member function for wrapped op2 void Legion Simple Legion op2 UVaL Reference LegionWorkUnit wu int parml parm2 UVaL_Reference lt LegionBuffer gt lb lb wu get parameter 1 lb get int amp parml 1 lb wu get parameter 2 lb get int amp parm2 1 int result object op2 parml parm2 generate MethodDoneEvent Return all results In this case there are three of them return value 3 in out parameters UVaL_Reference lt LegionBuffer gt return lb return lb new LegionBuffer return lb put int amp result 1 Legion return UVaL METHOD RETURN VALUE wu get continuation list return 1b return lb new LegionBuffer return lb put int amp parml 1 Legion return 1 wu get continuation list return 15D return lb new LegionBuffer return lb put int amp parm2 1 Legion return 2 wu get continuation list return 1b Reference page 125 June 19 2001 page 126 Legion 1 7 Reference Manual Invokes the appropriate method based on the function number in the supplied work unit int Legion Simple invoke method UVaL_Reference lt LegionWorkUni
21. attributes To get some idea of the current set of attributes consult the documentation on resource objects for the most up to date information invoke the retrieve_all_attributes method on a resource object and examine the results Examples of query strings are true This query would return the list of all objects contained in the collection match host os name SunOS This query would return the list of all objects contained in the collection with an attribute of the form host os name SunOS match host os name SunOS or Reference June 19 2001 Legion 1 7 Reference Manual match host os name Linux This collection would return the list of all objects contained in the collection with an attribute of either host os name SunOS or host os name Linux The following options are available v Run in verbose mode The resulting list of objects matching the query will be displayed along with the attributes of each object Otherwise only the list of matching objects without their attributes will be displayed debug Catch and print Legion exceptions help Print command syntax and exit The example below uses the default collection found in the etc context would be legion query collection etc Collection true 2 ALES 1 36ab9e4a 03 01000000 000001fc099204 1 36ab9e4a 07 01000000 000001 c04d6607 The output shows that there are two objects in the collection the
22. by the 1egion mplc script page 75 Itis responsible for parsing an MPL code and generating the appropriate C code Reference page 117 June 19 2001 Legion 1 7 Reference Manual legion_native_mpi_backend legion_permit_user legion_probe_object Backend script for legion_native_mpi_run The Legion admin installs this tool as a class usually in context space in class or Class HPC Installed using legion_register_program legion_native_mpich_wrapper legion_native_mpiibm_wrapper legion_native_mpisgi_wrapper legion_native_mpiultra_wrapper Site specific scripts used to determine how to start native MPI jobs at thatsite The Legion admin installs the appropriate tool when he orshe runs legion native mpi config host for the host object running at that site This tool tells whetherornota specific Legion usercan run on a specific host If a blank string is returned then the Legion usercannotrun on that machine If a non blank string is returned the string represents a Unix Windows user name and the legion user runs as that Unix Windows user on that machine Not necessarily an internal tool because any user can run it S pecifically used by 1egion make schedule to determine whether or not a user can run on a chosen host c object context path 1 object LOID gt A debugging tool for contacting a specified object Used for internal debugging If the tool cannot contact the object it tries to contact the rel
23. file Note thatthis file will only be passed to node 0 unless you use a This flag can be used multiple times to indicate multiple input files You can also use wild cards to specify groups of files Name of an output file that should be copied from the remote program s current working directory into your local directory after the program terminates Note thatthis file will only be passed to node 0 unless you use the a flag The new file will have the same name as the original output file unless a is used in which case the name will be name mpi object id This flag can be used multiple times Y ou can also use wild cards to specify groups of files Output files that are not found in the program s current working directory will be copied but will appear as empty files If the program crashes the files will be left in the program s current working directory Pass the files in the in out IN OUT parameters to all nodes The defaultsetting passes these files only to node 0 Files in the out oUT parameters will be copied to files that use the following conventions name mpi object id where name is the output file specified in the out OUT parameters 8 The output files will be copied out when the program calls MPI Finalize OfMPI_Abort Reference page 87 June 19 2001 page 88 Legion 1 7 Reference Manual stdin context path Map standard input to a Legion file obj
24. host name rw The rw indicates that the named host is allowed to read and write requests to legion The exportfile s default path is etc exports but you can specify another path with the exports file flag 11 Legion NFS mount relies on the mount and umount Unix command line utilities Please see the associated man pages for information aboutusing these tools Formore information aboutNFS mounts you can also see the exports mountd andnfsd man pages The two Legion NFS daemons and supporting materials were derived from the Unix User S pace NFS Server Version 2 2 Key contributors authors were Mark Shand Don Becker Rick Sladkey and Olaf Kirch Reference page 109 J une 19 2001 page 110 Legion 1 7 Reference Manual The following options are supported f exports file exports file local path S pecify a local path for the exports file page 109 Defaultis etc exports For security reasons the Legion NFS daemons are run locally so only the local host should be listed in this file In the future this will be mandatory and this option will be eliminated d debug facility Logoperations verbosely The current legal values for facility are call for logging RPC calls and arguments hcache for file handle cache operation and auth for authentication routines P port port number Specify a port number for 1mounta Default is a random number under 1024 Please note that unlike NFS mo
25. lt value gt Set the environment variable named in variable name to a specified value on all MPI processes after they have called MPI Init This option may be repeated multiple times to set additional environment variables Reference June 19 2001 Legion 1 7 Reference Manual help P rint command syntax and exit Assuming that you do notuse an option file the MP I application named inthe legion mpi run command will be started with the given flags For example to run MPI program vdelay on two hosts you would enter legion mpi run n 2 mpi programs vdelay Use legion 1s to examine the running objects of your application The mpi instances program name context is the default location of your application s instances legion 1s mpi instances vdelay If you run multiple versions of an application simultaneously you can use the p flag to specify a different context to hold your instances Specification file A specification file is a text file that contains a list of hosts and the number of Legion objects that can be scheduled on those hosts Objects from your application s will be scheduled on these hosts You can use 1egion make schedule to produce this file or create it by hand Listone hostand one integerindicating the number of objects the host can create the default is 1 per line List hosts by their Legion context names A host can be listed multiple times in one file in which case the
26. size array has atleast nfields elements LegionLOID protected Parameters int type short nfields short fld size char fld value Sets the type to 1type Sets num fields to nfields Allocates the ield size and field value arrays Sets all ield size s to the values contained in the fld size array Allocates the ield value entries to the right size and copies the values from 1d value array into the ield value array This constructor assumes that the 1d size and fld value arrays have at least nfields elements and that each 1d value i points to at least 1d size i bytes of space set field size protected Parameters short field num short fsize Sets the appropriate field size element to fsize and makes sure that the corresponding ield value elementis at least size bytes If it is not it deletes the old ield value entry and allocates a new one Only derived classes should be allowed to call this member set type protected Parameters int new type Sets the type entry to be new type Can only be called from within the code of derived classes page 136 Reference June 19 2001 Legion 1 7 Reference Manual LegionLOID Parameters LegionBuffer amp lb LegionLOID Parameters LegionLOID amp otherLOID These two constructors are public because neither allows the caller to violate the structure of any particular type of LOID both just copy the LOID from the parameter
27. 1 if the object is a Class 0 if the object is nota Class User Responsibility None int isHost LegionldType ldType char ObjName Determines if the indicated object is a Host object or not Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to test Return Values 1 if the object is a Host 0 if the object is not a Host User Responsibility None int isVault LegionldType ldType char ObjName Determines if the indicated object is a Vault object or not Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to test Return Values 1 if the object is a Vault 0 if the objectis nota Vault Reference page 165 J une 19 2001 Legion 1 7 Reference Manual User Responsibility None int isTTY LegionldType IdType char ObjName Determines if the indicated objectis a TTY objector not Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to test Return Values lifthe objectis a TTY 0 if the objectis nota TTY User Responsibility None int islmplementation LegionidType IdType char ObjName Determines if the indicated object is a Implementation object or not Parameters IdType Flag indicating whether parameter is a LOID or
28. 2001 Legion 1 7 Reference Manual legion register program program class executable path legion arch debug help This command allows uses to register an independent i e not linked to the Legion libraries executable program specified by the executable path argument and make the program available for use within the Legion system If the program was not previously registered a new class objectthe registered program will be associated with a Legion class object named in programclass the class and the context path will be created The registered program will execute only on hosts of the architecture specified in lt legion arch Programs registered through 1egion register program can be executed with the 1egion run command page 100 See also legion register runnable for information about registering Legion programs below The following parameters are used with this command program class The Legion context path name of the class with which the registered program should be associated executable path The local file path of the executable program to register This can be any program that could be run from the shell command prompt including scripts and binary executable generated by any programming language legion arch The platform type on which the program should be executed The following options are supported debug Catch and print Legion exceptions help Print command
29. Error Return NULL Reference page 145 J une 19 2001 Legion 1 7 Reference Manual User Responsibility The user is responsible for free ing the LOID return value char GetMyLOID Returns the LOID of the running object program Parameters None Return Values LOID of the current running program Error Return NULL User Responsibility The user is responsible for free ing the LOID return value 8 2 Exceptions The following section describes functions which interface with the Legion Exception interface extern int CLEGION_CONTINUE_ON_EXCEPTION These variables correspond A extern int CLEGION EXIT ON EXCEPTION the valid values that can be pA extern int CLEGION CANCEL METHODS ON EXCEPTION used as flags when enabling extern int CLEGION NO MESSAGE ON EXCEPTION an exception catcher x void Legion ExceptionCatcherDefaultEnable int Flag Enables a default Legion Exception Handler with user indicated properties Parameters Flag A value from the valid flags listed above which indicates what the handler should do when a Legion exception is caught Valid values include CLEGION CONTINUE ON EXCEPTION CLEGION EXIT ON EXCEPTION CLEGION CANCEL METHODS ON EXCEPTION CLEGION NO MESSAGE ON EXCEPTION Don t do anything Return Values None UserResponsibility None page 146 Reference J une 19 2001 Legion
30. June 19 2001 2 9 Legion 1 7 Reference Manual Application development legion bfs file help o out file gt BackEnd Parses Fortran programs containing Legion Basic Fortran Support BFS pseudo comments to produce standard Fortran output or parses Legion BFS IDL files to produce Mentat Programming Language MPL output Ifthe input ile ends with ff itis treated as Fortran with pseudo comments If the input lt file gt ends with bfs itis treated as BFS IDL The following options are used o out file Name of the file containing the resulting Fortran or MPL output BackEnd Instructs the legion_bfs compiler to produce output for IDL files included in the Fortran input file ignored when the input is a BFS IDL file debug Catch and print Legion exceptions help Print command syntax and exit legion_make v a lt architecture gt h host context path gt e make command gt OUT remote file gt lt argl gt lt arg2 gt lt argn gt debug help Compiles programs on a remote host The command tars your current directory copies it to a remote host untars it and executes a make command The resulting compiled binaries can be registered with Legion via the directory s makefile orcan be copied backto yourcurrent directory with one or more ouT options Be aware that1egion make will tar everything in and below your current directory so be sure that you are in
31. MethodReady event A MethodReady event is generated every time a ready invocation is inserted into the invocation store static int LegionMethodInvoke UVaL_Reference lt LegionEvent gt event UVaL_Reference lt LegionBuffer gt lb int parameter if LegionInvocationStoreLL_Default gt any_ready UVaL_Reference lt LegionWorkUnit gt wu wu LegionInvocationStoreLL_Default next matched wrapper invoke method wu return 0 f int main int argc char argv Legion init wrapper new Legion Simple Legion AcceptMethods wrapper accept member functions endif oe xl Simple c include lt stdio h gt include Simple trans h include legion Legion h UVaL_Reference lt LegionParameter gt make_int_parameter int parm_value int parm_number UVaL_Reference lt LegionBuffer gt 1b UVaL_Reference lt LegionParameter gt parm lb LegionBuffer new LegionBuffer lb put int amp parm value 1 parm LegionParameter new LegionParameter parm number 1b return parm int main int argc char argv Variables for the user code inta 10 b 15 int Xx y Z Reference page 127 June 19 2001 page 128 Legion 1 7 Reference Manual Initialize legion state All of the below to get a random instance number int my instance number struct timeval tv gettimeofday amp tv NULL srand tv t
32. Moda 122 6 2 Simple trans h and Simple trans C naana aaa 123 6 3 exl Simple e coss cu ae dL aad UC LE 127 Reference page 3 J une 19 2001 Legion 1 7 Reference Manual 7 0 Interfaces 130 7 1 LegionP rogramGraph suasanana saaana eanan 130 7 2 LegionlnvocationStore a sasaaa aaaeeeaa a 131 7 3 LegionWorkUnit ois qe ol deese out iie c udi Er p MAE ted 132 7 4 LEGIONB UMA eod sive uu REN Hr ce OE a awe 132 7 4 1 LORStr btDES ovt dk an REFER RR ER EE PERRO AREA DES 132 7 4 2 Operations on the associated LegionStorage ssss 133 7 4 3 Operations on the associated LegionPacker sssr 134 7 4 4 Operations on the associated LegionE ncryptor 135 7 4 5 Operations on the associated LegionCompressor 135 7 4 6 LeoionPackable eus cata eit on te Na EO Edda 135 7 4 7 Omer functions aa verarbeiten De nr dann 135 7 4 8 Naming and binding LegionLOID sssennn 135 1 5 L gionMessage oes rote ete RED RE Ee Rost 138 7 5 1 LegionParametef s odoeodve a ra o eon iv Tad vu rv WE 138 7 5 2 LegionParameltert ist ot i env ro ea 139 7 5 3 LegionComputationTag icem o Eten 140 7 5 4 OTOP TOIOS anos eum t oe Ue E T SE 140 Legion Grid library 8 0 Grid library 141 8 1 L gion Library interface sess 5 4 utram acr Pesca A9 E De Ste ed 143 8 2 EXCEDNONS x51 3 vans rd uw sis ahd Oat Rs RETE ERRAT E Sue Roast ss 146 8 3 LegioircontexEsDate s sod eese ara RUN EO RUND 147 8 4 Legion object management
33. Reference page 173 J une 19 2001 Legion 1 7 Reference Manual char RetrieveAttributeSig LegionldType ldType char ObjName char AttributeSig Retrieve an attribute from an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName Either the context path name or the LOID of the object to which the attribute will be added AttributeSig The string representation of the signature of the attribute to retrieve from the object s attribute database Return Values The string representation of the attribute retrieved Error Return NULL User Responsibility The user is responsible for free ing the returned attribute char RetrieveAttributeSigs LegionldType ldType char ObjName char AttributeSigs Retrieve a list of attributes from an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to which the attribute will be added AttributeSigs A NULL terminated list of the string representations of the signatures of attributes to retrieve from the object s attribute database Return Values A NULL terminated list of the string representations of the attributes retrieved Error Return NULL User Responsibility The user is responsible for free ing each returned attribute in the list as well as for free ing the list
34. Specifies the OPR address for the object i e a unique directory in which the object will maintain its persistent representation on the remote host binary path Binary executable path for the object on the remote host Optional parameters do the following user id Specifies the appropriate user name on the rsh host debug Catch and print Legion exceptions help Print command syntax and exit legion deactivate object stay down tLe page 16 debug help object context name 1 object LOID gt Deactivates the objectnamed in lt object LOID Or context path moves itto an inertstate if itis currently active If the objectis already inactive the command has no effect The following options are supported stay down Forces object to stay inactive It can only be reactivated by 1egion allow activation page 26 debug Catch and print Legion exceptions help P rint command syntax and exit Reference J une 19 2001 Legion 1 7 Reference Manual legion destroy object c lt object context name l object LOID gt debug help Deletes the object named in context path Or object LOID gt More specifically itremoves the object s LOID butnotits contextname if there is one If the object is active the command deactivates the object In all cases it deletes the OPR object persistent representation associated with the object This command will not rem
35. This is the wrapped object static Legion Simple wrapper This is the event handler for invoking a method static int LegionMethodInvoke UVaL_Reference lt LegionEvent gt Generates a MethodDone event Should be called right after the call to the wrapped object s member function void Legion Simple generate MethodDoneEvent UVaL_Reference lt LegionEvent gt methodDoneEvent methodDoneEvent new LegionEvent LegionEvent MethodDone void NULL LegionEventManagerDefault announce methodDoneEvent LegionEventAnnounceNow Allocates the wrapped object and enables th corresponding functions in the invocation store Legion Simple Legion Simple object new Simple wrapper this enable functions LegionInvocationStoreLL Default FI De allocates the wrapped object Legion Simple Legion Simple delete object wrapper NULL Reference June 19 2001 Legion 1 7 Reference Manual wrapper member function for wrapped opl void Legion Simple Legion opl UVaL Reference LegionWorkUnit wu get the parameter from the work unit int parml UVaL_Reference lt LegionBuffer gt lb lb wu get parameter 1 lb get int amp parml 1 Invoke the wrapped member function int result object opl parm1 generate MethodDoneEvent Return the result
36. a context path name or a LOID HostName The name of the host to kill the object on binding The binding to the objectthat you wish to kill actld The host s activation id for the object to kill Return Values 1 on Success 0 on Failure User Responsibility None int HostDeactivateObject LegionldType HidType char HostName CLegionBinding binding int actld Ask the host to deactivate an object itis running Parameters HIdType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host to deactivate the object on binding The binding to the object that you wish to deactivate actld The hosts activation id for the object to deactivate Return Values 1 on Success 0 on Failure User Responsibility None page 182 Reference J une 19 2001 Legion 1 7 Reference Manual CLegionHostObjectStatus ListObjects LegionldType HldType char HostName Ask the host to return a list of objects that it is currently managing Parameters HIdType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host to acquire the list from Return Values A NULL terminated list of CLegionHostObjectStatus s Each array element represents the status of one object currently being managed by a host Error Return NULL User Responsibility The user is responsible for destroying each CLegionHostO bjectS tatus in the list as well as for free
37. be placed Note that if you identify the instance by its context path you must use context paths in the lt vault1 gt vault2 vaultn parameter If you use a LOID with the 1 flag you mustuse LOIDs in the vaulti1 vault2 vaultn parameter The following optional parameters are supported 1 Use LOIDs to specify instance and vault a Add named vaultto the instance s acceptable vaultlist d Delete named vault from the instance s acceptable vault list t Test whether or not a vault is on the instance s acceptable vault list p Display the instance s acceptable vault list debug Catch and print Legion exceptions help Print command syntax and exit You canuse the a a and t flags more than once when running the command but regardless of how you list them on the command line Legion will process themin a specific order when you run the command first adding any new vaults then deleting old vaults then testing any vaults and finally printing out the results legion_join_collection c collection context path 1 collection LOID gt c member context path 1 member LOID gt debug help This command joins the objects named in lt member LOID gt or member path to the collection named in collection LOID gt Or collectionpath AnyLegion objectcan be added to a collection You can use the 1egion query collection command page 51 to get information in the fo
38. be used for adding new host or vault objects with the command line procedure to a system spanning multiple file systems or to a Legion system with a common file system For a system spanning multiple file systems however skip steps 2 and 3 In either case the main Legion system must be active Start it with the first time start up or restart procedure if necessary 1 Login to the desired machine 2 Create the LEGION and LEGION OPR directories on the new machine if they do not already exist 3 Copy the following files from your Legion system s LEGION OPR directory to the new machine s LEGION OPR directory if they do not already exist legion context env sh legion context env csh LegionClass config LegionClass config LegionStorage MetaData 4 Setthe environmenton the new machine ksh or sh users SLEGION bin legion env sh SLEGION OPR legion context env sh csh users source SLEGION bin legion env csh source SLEGION OPR legion context env csh 5 Onthe new machine start up the host legion startup local You will prompted as to whether or not you wish to start a host and vault object We recommend that you answer yes to both 13 If preferred ssh can be used in place of rsh Reference page 119 J une 19 2001 Legion 1 7 Reference Manual 5 2 Shutting down extra hosts and vaults command line 1 Shut down the main system see page 26 in the System Administrator Man
39. bootstrap host and the bootstrap vault legion remove sub collection 1 collection LOID gt c collection path l member LOID gt c member path q lt query gt This command ends a parent subcollection relationship It does not destroy either collection You must name the parent collection and the subcollection If the parent collection is running multiple queries on the Subcollection use the q flag to stop a specific query use legion list sub collections page 50 to see which queries are running on which subcollections Otherwise all queries will be stopped The following option is supported q query A MESSIAHS style query that is being run on the subcollection See 1egion query collection page 51 for details legion set default placement c lt class context path 1 class LOID gt c host context path 1 host LOID gt c vault context path 1 vault LOID gt debug help Sets the default placement for objects of the class named in lt class LOID Or class context name gt to the given host vault pair Default Reference page 53 June 19 2001 Legion 1 7 Reference Manual placementis used when a class has no associated scheduler object or cannot contact its associated scheduler object When a default placement is set the user should take care to ensure that an implementation for the default placement hosts architecture is
40. char NewAttribute Replace an attribute in an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to which the attribute will be added Reference page 169 J une 19 2001 Legion 1 7 Reference Manual OldAttributeSig 2 The string representation of the old attribute s attribute signature NewAttribute The string representation of the new attribute to put into the database This is of the form attribute signature attribute value Return Values 1 on Success 0 on Failure User Responsibility None int ReplaceAttributes LegionldType IdType char ObjName char OldAttributes char NewAttributes Replace a list of attributes in an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the objectto which the attribute will be added OldAttributes A NULL terminated list of the string representations of the old attributes to replace in the database These are of the form attribute signature attribute value NewAttributes A NULL terminated list of the string representations of the new attributes to put into the database These are of the form attribute signature attribute value Return Values 1 on Success 0 on Failure User Responsibility None int ReplaceAttributeSigs eg
41. contain the latter set of implicit parameters and they will affect the creation of all subsequent objects This option is intended to make it easier to administer the system In particular admin can create user accounts that include implicit parameters that by default give the admin access rights to all of the users subsequently created objects Include the new user id s password in the command line This option is not recommended for casual use since the password can potentially be seen by other users while the command is operating Catch and print Legion exceptions Print command syntax and exit J une 19 2001 Legion 1 7 Reference Manual legion get acl c lt object context path 1 object LOID gt debug help Returns the access control listofthe objectnamed in lt object LOID gt or object context path or if no object is named the default access control set associated with the current logged in Legion session This command returns 2 as its exitstatus ifthe object session has no access control list The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_get_implicit_params c lt object context path gt 1 lt object LOID gt debug help Getthe implicit parameters of the object named in object LOID Or object context path Or if no object is named the current logged in Legion session The formeris ana
42. could not be deleted because it was not empty To get around this keep retrying the operation until all entries are removed and the parent context can be deleted Reference June 19 2001 Error codes Legion 1 7 Reference Manual The LegionClientExith file contains the declarations for the error reporting mechanism for these command legion activate instances legion activate object legion cat legion classof legion context add legion cp legion deactivate object legion get host legion get vault legion list instances legion list names legion list objects legion login legion logout legion 1s legion ping legion print config legion pwd legion rm legion set vault legion wellknown class legion whereis legion whoami Below are the identifiers and their codes LC_SUCCESS 0 LC_BAD_ARGUMENTS 1 LC_MEMORY_ALLOCATION_ERROR LC_OBJECT_NOT_FOUND 3 LC_CONTEXT_NOT_FOUND 4 LC_OBJECT_DOES_NOT_EXIST LC_OBJECT_ALREADY_EXISTS LC_LOID_NOT_OBTAINED 7 LC_LEGION_OUTCALL_FAILED LC_SECURITY_EXCEPTION 9 Reference line utilities legion_deactivate_instances I N page 115 J une 19 2001 Legion 1 7 Reference Manual LC GENERAL LEGION ERROR LC UNKNOWN LEGION ERROR LC OTHER ERROR 12 I p e II p page 116 Reference J une 19 2001 Legion 1 7 Reference Manual 4 0 Internal tools These tools are used
43. exit context path debug help page 26 Changes the current working context to the context named in context path Note thatthe path name can be relative or absolute This command is analogous to the Unix cd command The following options are supported Reference June 19 2001 legion context add object LOID context name debug help Legion 1 7 Reference Manual debug Catch and print Legion exceptions help Print command syntax and exit Adds a new name lt context name gt forthe objectnamed in lt object LOID gt to the current context space The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_context_create context path legion cp debug help Creates a new contextin Legion contextspace and assigns itthe name given in context path This command is analogous to the Unix mkdir command The new context will be placed in your current context The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit aa e debug m p localsrc localdest V lt vault context path gt lt source path gt lt destination path gt help Copies the file object or tree named in lt source path gt named as either a context path or a local path to a new duplicate file object or tree named in lt dest ination path named as either a c
44. exit Reference page 31 J une 19 2001 Legion 1 7 Reference Manual legion 1n context path new alias debug help legion 1 Assigns an additional name given in new alias to the object namedin context path Analogous to the Unix 1n command Path names can be relative or absolute An objectcan have multiple context names assigned by one or more users The same context name can be assigned to different objects or to the same object so long as the contexts names are in different contexts justas the same file names can be used in different levels of a Unix directory The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit S laLRAdqv lt context path gt debug help page 32 Lists the contents of a named Legion context in ascii alphabetical order Note that the pathname can be relative or absolute The command is analogous to the Unix 1s command The default setting lists the current context You can include a context path in the lt context path gt parameter to list the contents of that context For example legion_ls hosts BootstrapHost my host DNS name Youcan getmore specific information objecttype LOID othercontext aliases state about objects with the flags For example you can get more information about a particular context s objects with the 1 a and A flags The output below shows a complete list of al
45. get continuation list Parameters None Return the continuation list for the results of this work unit UVaL_Reference lt LegionBuffer gt get parameter Parameters int parameter number Returns the given parameter as a LegionBuffer NULL if the parameter is not in the work unit 7 4 LegionBuffer 7 4 1 Constructors LegionBuffer Parameters None The default constructor is for the common case it creates an empty buffer with a LegionStorageScat Storage and default implementations of the packer compressor and encryptor function sets LegionBuffer Parameters UVaL_Reference lt LegionStorage gt The simple constructor wraps a default buffer around a given storage object It uses default implementations for the packer encryptor and compressor page 132 Reference June 19 2001 Legion 1 7 Reference Manual LegionBuffer Parameters LegionMetaData metadata The meta data based constructor creates a new empty LegionBuffer With a LegionStorageScat default storage implementation It instantiates packer encryptor and compressors based on the meta data LegionBuffer Parameters UVaL_Reference lt LegionStorage gt LegionMetaData metadata The full featured constructor wraps a specified storage in a buffer appropriate for the given meta data selecting the right packer meta data compressor and encryptor implementations 7 4 2 Operations on the associated LegionStorage A LegionStorage exports member functions to rea
46. gt IN local file path gt OUT lt local file path gt showscratch pwd hostname list stat remote file path gt delete remote file name gt statjob signal number kill setscratch context path gt p robe lt local file path gt This command checks a program started on a remote host with legion_run page 100 Itcan also pass inputfiles to or pick up output files from the remote host check individual files associated with the job and clean up the remote host space It can be used with blocking or nonblocking runs although itis especially useful with nonblocking runs You must have used the p option when starting 1egion_runin order to use this command this option creates a local file called a probe file thatcan contact your remote job If you do nothave a probe file for your job legion_probe_run will be unable to locate your job Note that if you start a nonblocking run the remote host will hold the results for six hours after the job terminates If you do nothing the host will tar up the job s current working directory and move it into your context scratch space If you run legion_probe_run at any point whether to retrieve output files or just to check the job s status during those six hours the clock restarts and the remote host will wait for another six hours before tarring and moving the job s directory If you do not use the kill option to clean up the job s dire
47. integer values accumulate E g hosts BootstrapHost 5 hosts slowMachinel hosts bigPBSqueue 100 hosts slowMachine2 1 The file can be in your local directory or contextspace Use hf or HF to use the file when running 1egion mpi run All of the objects from this Legion MPI run will be created using vector creates Wild cards You can also use wild cards to work with groups of input output files The following wild cards can be used with in out and IN OUT Match 0 or more characters Match any one character Match any character listed between the brackets use these to specify a range of characters Treat the character as a literal 9 Ina secure system the default context is home lt user_name gt mpi instances lt program_name gt Reference page 89 June 19 2001 page 90 Legion 1 7 Reference Manual For example if you wanted to identify done 1 done 2 done 3 done 9 as yourinputs you could use square brackets to identify them as a group legion mpi run n2 IN done 0 9 mpi programs mpiFoo You can use wild cards on the command line or in an option file They can only be used with file names however not with directories Option file The option file contains a list of all MPI applications that you wish to execute as well as any necessary arguments as they would appear on the command line All applications must have been registered with legion mpi register andus
48. itself page 174 Reference J une 19 2001 Legion 1 7 Reference Manual char RetrieveAllAttributes LegionldType IdType char ObjName Retrieve all of the attributes from an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the objectto which the attribute will be added Return Values A NULL terminated list of the string representations of the attributes retrieved Error Return NULL User Responsibility The user is responsible for free ing each returned attribute in the list as well as for free ing the list itself 8 6 Interfaces to Legion objects The following function deals with the interfaces to Legion objects char Getlnterface LegionldType char ObjName Retrieve all of the method signatures for a Legion object Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to retrieve the interface for Return Values A NULL terminated list of the string representations of the method s which are currently part of the indicated object s interface Error Return NULL User Responsibility The useris responsible for free ing each returned signature in the list as well as for free ing the list itself Reference page 175 J une 19 2001 Legion 1 7 Reference Manual 8 7 Legion C type manipulat
49. object does not respond to the ping within that amount of time legion_ping will exit Please note Reference page 9 June 19 2001 Legion 1 7 Reference Manual that legion ping failing due to a user specified time out does not necessarily mean that the object is inactive or otherwise unreachable There is no default time out setting debug Catch and print Legion exceptions help Print command syntax and exit legion list attributes object context name gt 1 object LOID gt t c L lt attribut name gt debug help Lists an object s attributes fromthe command line O ptional parameters do the following L Lists the LOID of each attribute attribute name S pecify the attribute to be listed more than one attribute can be listed debug Catch and print Legion exceptions help Print command syntax and exit A very simple example ofthis command is below An object s attributes can include architecture operating system information host or vault compatibility encryption information etc legion list attributes Foo Foo ALL Total attributes retrieved 1 favoritecolors puce apricot legion_list_invocations c object context name gt 1 object LOID gt debug help legion object info object context name 1 object LOID gt debug help ti e v page 10 Prints a list of currently pending started and recently completed invoca
50. of three things A basic integral type e Another C typedef for a C class a char which is the LOID ofthe value requested User Responsibility When a C typedef for a C class is returned the user is responsible for Destroying that type when done When a char is returned the user is responsible for free ing the dynamically created memory 8 8 Legion host object The following section contains functions which are used to make calls directly on host objects CLegionHostReservation MakeReservationFromHost egionldType HidType char HostName LegionldType VldType char ReqVitName Ask a hostto make a reservation for either an instantiation or an activation Parameters HIdType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host with which the reservation should be made VidType A flag indicating whether R eqVItName is a context path name or a LOID ReqVItName The name of the vault to be paired up with this host reservation Return Values The CLegionHostReservation that represents the HostR eservation just made Error Return 0 User Responsibility User is responsible for destroying the host reservation when done page 180 Reference J une 19 2001 Legion 1 7 Reference Manual CLegionHostReservationRecord CheckHostReservation LegionldType HidType char HostName CLegionHostReservation HstRes Check on the status of a host reservation previously m
51. of work requests that a worker may service at a given time The current version of the proxy object uses a self scheduling algorithm When N work requests have been farmed out the proxy will store any pending requests in an internal queue when a worker is available the proxy assigns it a request from the queue N here is given by the following formula N number of replicas max number of workers The following options are supported n number of replicas Specify the number of workers to be used Defaultis 1 Ch context containing list of hosts Name a hostwhere the work requests should be executed w max number of work requests Specify the maximum number of work requests that each worker should service ata time Defaultis 5 FlUsH Remove all work requests for this class You must spell this flag as written with proper capitalization Reference J une 19 2001 Legion 1 7 Reference Manual debug Catch and print Legion exceptions help Print command syntax and exit legion stateless remove workers lt class name worker namel gt worker name2 gt worker nameN gt debug help Removes MPL stateless object workers The class name parameter should be the stateless class object s context name The worker name parameters should be the context name of the unwanted worker objects Note that you can use full or relative path names The following options are supported debug Cat
52. page 202 Reference June 19 2001 Legion 1 7 Reference Manual Getting help E mail Contact Information On Line Help Please contact us at one of the addresses listed below if you have trouble with the system Please be sure to include any relevant information about the state of your system before and during the problem We would greatly appreciate hearing from you whenever you find errors or bugs in Legion so that we can avoid similar problems in future releases For bug reports help and general Legion information please send an e mail message to legion help virginia edu Legion Group Department of Computer Science S chool of Engineering amp Applied Science University of Virginia 151 Engineer s Way P O Box 400740 Charlottesville VA 22904 4740 http legion virginia edu fax 434 982 2214 A variety of technical notes reports and on line tutorials are available on the Legion web site at lt http legion virginia edu gt Reference page 203 J une 19 2001 Legion 1 7 Reference Manual Index A accept member functions 122 accounting logs 57 architectures available in Legion 103 108 B bootstrap host 120 C cat 26 CError h file 115 141 202 CLegionLib h file 141 commands documentation 6 legion_2drm 37 legion_activate_instances 26 legion_activate_object 14 legion_add_acl 62 legion_add_class_mapping 22 legion_add_host_account 38 legion_add_implicit_params 62 legion_add_sub_co
53. run By setting a new currenttty object the outputcan be redirected to any window or even a file Forexample legion create object c class ttyObjectClass my tty legion set tty log file creates a tty object whose output is sentto a file To view the tty output use the 1egion tty watch command below The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit tty context path debug help legion tty off debug help This command can be used to direct all output from a particular shell backto thatshell i e create and seta tty objectfora shell in one step rather than running legion create object legion set tty and legion tty watch lf no tty object exists at the path named in tty context path itcreates a new object sets itas the target tty and starts the legion tty watch process in the background of the shell in which the command was run If a tty objectalready exists atthe named context path the command sets that tty object as the target Please see page 75 in the Basic User Manual for a discussion of tty objects The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Unsets stops the Legion tty object for the current shell so that Legion programs executed in thatshell after Legion_tty_off is run will not display their outputto a Legion tty object This command
54. seek setMetaData size write LegionW orkUnit get_continuation_list get function number get parameter library implementation interfaces In ls 137 138 138 140 140 140 138 140 138 138 138 138 135 135 134 135 134 138 139 138 139 139 139 139 139 139 139 139 140 139 139 140 130 130 130 130 130 131 131 133 134 134 134 133 133 134 134 133 132 132 132 132 130 32 Reference Legion 1 7 Reference Manual page 213 J une 19 2001 M Mentat message layer changing security mode mkdir mv N naming and binding LegionLOID P ping pwd R m runtime library exl Simple c examples and interfaces Simple c Simple h Simple trans c Simple trans h S simple class start a single system on two hosts start up host U user profile V vault object adding new command line procedure adding new rsh procedure restart extras command line shutting down extras command line page 214 Legion 1 7 Reference Manual 75 27 33 34 135 34 127 122 122 122 123 123 122 120 120 119 119 120 120 Reference
55. select during 1egion setup state and that contains the basic Legion classes is the start up host The bootstrap host is used to boot the system and is the first host object added to the system It will contain the first pieces of the new system the first contexts and instances of the classes In either case Legion binary executable files must be installed on any hosts used for Legion page 120 Reference June 19 2001 Legion 1 7 Reference Manual procedures That is you don t have to run legion startup in order to use the hostin a Legion net you justhave to have the binary files Y ou do not have to run legion_initialize on the same hoston which you run legion_setup_state and legion startup Figure 1 Start up and Bootstrap hosts Start up host Start up host characteristics Contains Legion binary executable files No start up host object Bootstrap host characteristics Contains Legion binary executable files First host object added to system Contains first pieces of the system Bootstrap host Bootstrap host object Reference page 121 J une 19 2001 Legion 1 7 Reference Manual Runtime library examples and interfaces 6 0 Example translations the simple class The simple class in this example is a nonsense class that does no meaningful computation However it exercises the library s full functionality and illustrates how our compiler generates tran
56. that make extensive use ofthe in out or IN OUT options The file can contain one or more of the legion run flags delimited by spaces tabs or blank lines The program class name and any arbitrary command line arguments may not be included in this file No other information should be included argl arg2 argn Allows users to provide arbitrary command line arguments for the program The possible architectures that can be used with the a flag are limited Atthe moment they are Architecture Corresponds to Comments solaris Sun workstations running Solaris 5 x sgi n32 n64 SGI workstations running IRIX 6 5 linux x86 running Red Hat 6 x Linux alpha linux DEC Alphas running Red Hat 6 x Linux alpha DEC DEC Alphas running OSF1 v4 rs6000 IBM RS 6000s running AIX 4 2 1 hppa hpux HPUX 11 t90 Cray T90s running Unicos 10 x virtual hosts only see page 69 in the System Administrator Manual t3e Cray T3E running Unicos mk 2 x virtual hosts only see page 69 in the System Administrator Manual For more information on this command please see Running a Legion application on page 35 in the Basic User Manual Reference page 103 June 19 2001 legion_run_multi d ir lt dir gt help debug e xec command D lt var value gt n number of processors s chedule lt schedfile gt Legion 1 7 Reference Manual v erbose z ero r e
57. the objectis still active the backup vaults will not have the object s current State If the object needs to be reactivated it will use an out of date State This overwrites any policies set via 1egion class vault list page 46 If you do not use 1egion skcc set class vaults Legion will use the class vault restriction lists as specified with legion class vault list The specified class must belong to the SKCC metaclass Current members are BasicFileClass ContextC lass ImplementationO bject and UserAuthenticationO bject You can use legion set backup vaults to set vaults for a specific instance page 18 Note however that legion_set_backup_vaults will overwrite the policy set by legion_skcc_set_class_vaults for that instance The following parameters must be used 1 lt SKCC class LOID gt Or c SKCC class context path Specify an SKCC class object a Addthe specified vaultto the object s listof backup vaults d Delete the specified vault legion skcoc set defaults 1 SKCC class LOID gt c lt SKCC class context path number of default vaults S pecifies default level of state replication for instances of an SKCC class Legion will now by default attemptto copy the instances state on the specified numberofvaults Y ou mustbethe class s ownerto setthis default Reference page 11 June 19 2001 legion set worm c lt object context path 1 object LOID gt Legion 1 7 Referenc
58. the class by its context name in the first parameter i e myClass you must use context names in the hostl host2 hostn parameter If you use a LOID with the 1 flag you must use LOIDs Reference page 45 June 19 2001 Legion 1 7 Reference Manual The example below adds a new hostto the list of acceptable hosts of BasicFileClass using the a flag legion class host list class BasicFileClass a hosts newHost ADDED 1 host s to class s acceptable host set The p flag can then be used to check the listing legion class host list class BasicFileClass p ACCEPTIBLE HOST LISTING id 1 01 07 d59d1a40 000001 c094e23 The following optional parameters are supported 1 Use dotted hex LOIDs to specify class and host a Add named hostto the class s acceptable host list d Delete named hostfrom the class s acceptable hostlist t Test whether or nota hostis on the class s acceptable host list p Display the class s acceptable host list debug Catch and print Legion exceptions help Print command syntax and exit You canuse the a a and t flags more than once when running the command but regardless of how you list them on the command line Legion will process themin a specific order when you run the command first adding any new hosts then deleting old hosts then testing any hosts and finally printing out the results legion_class_vault_list
59. the correct directory before running it If no remote hostor architecture is specified with the h or a flags the command will run on a random host For example the following command would build the tar file on a random Alpha Linux host legion make a alpha linux To be more specific use the n flag legion make h hosts HostFoo The following options are supported v Run in verbose mode up to four of these flags may be used Reference page 73 June 19 2001 legion make multi 7v a lt archit lt argl gt lt arg2 gt debug page 74 help Legion 1 7 Reference Manual a architecture S pecify what kind of platform should be used to execute the command h host context path Specify which host should execute the program e make command S pecify an executable command other than make to be run on the remote host OUT result file gt S pecifies the local path name of a file that should be copied out of the remote program s current working directory after the program terminates The default setting does not copy anything back to your current directory argl arg2 argn Optional arguments passed to the make commands they can specify make targets or other build parameters debug Catch and print Legion exceptions help Print command syntax and exit cture gt lt make command gt lt argn gt Compile a program on multiple platforms
60. type gt and function signature arguments specified in the argument list Sends this interface to the object specified by lt LOID gt or context path in the form of a call to the object mandatory function named exportsInterface Prints to standard output the return value from the call 1 if the interface of the object contains the entire interface of functions specified by the user if any one or more ofthe functions are not exported by the object 1 without contacting the specified object if the user creates a malformed argument list The well knownclasstype argumentis a string in the setof well known strings The setcan be listed with 1egion wellknown class see page 60 For this tool s purposes C1assObject is a well known class string CommandLineClass and BootstrapMetaClass are not considered well known classes because they do nothave any special member functions as shown in the examples below legion exports interface class LegionClass w ClassObject i legion exports interface class LegionClass w CommandLineObject CommandLineObject is nota well known class Exiting i legion exports interface class LegionClass w LegionClass w ClassObject 1 legion exports interface hosts BootstrapHost V w UnixHostClass 1 legion exports interface hosts BootstrapHost V w ClassObject 0 Reference J une 19 2001 Legion 1 7 Reference Manual legion e
61. up basic Legion services The following optional parameters are supported local Starts up only a local host or vault debug Catch and print Legion exceptions help Print command syntax and exit L lt SLEGION gt O lt SLEGION_OPR gt A lt LEGION_ARCH gt N context name gt U user id gt C vault class host name compatible host list gt debug help AN Creates a new vault object on the specified nost name using the legion create object r command automatically invoked on the host class page 15 The host name is the host s DNS name This command uses remote shell rsh or ssh classes to start a new vault object on a specified host Please note that you mustbe able to run rsh ssh on the target host from your current machine without having to enter a password Y ou can setup an rhosts file for rsh oran authorized keys file for ssn to accomplish this see the rsn and ssh man pages for further information You can run Legion commands on a remote host using rsh or ssh once you set the proper environment variables For sh ksh or bash use EGION RSH rsh ssh EGION_RCP lt rcp scp gt export LEGION_RSH LEGION_RCP Forcsh use setenv LEGION_RSH lt rsh ssh gt setenv LEGION RCP rcp scp The following optional parameters are supported Reference page 43 J une 19 2001 page 44 L lt SLEGION gt O lt SLEGION_
62. v context path list help Removes the context path s named in context path list from Legion context space Pathnames can be relative or absolute Analogous to the Unix xm command If the context path listed is the last i e only name mapped to a given object the object will be destroyed You can now use wildcards in the context path list parameter Please note that you must escape the character l e to remove all context objects containing foo in their names you would enter legion rm foo Optional parameters do the following r Recursively remove one or more contexts and all of their contents f Forcibly remove faulty objects those with bad bindings v Run this command in a verbose setting This is useful for checking whether or notan object is removed debug Catch and print Legion exceptions help Print command syntax and exit Reference June 19 2001 legion set tty tty context path debug help legion tty Legion 1 7 Reference Manual This command will set an environment variable to indicate which tty object should be used by subsequent programs Please see page 75 in the Basic User Manual for a discussion of tty objects By selecting a new currenttty object users can redirectthe outputto any window or file legion set tty context path my tty Note that program output does not have to be directed to the same window in which the program is
63. you mustlogin as admin in order to use the system Use the 1egion login command with users admin as the user name gt parameter This command only needs to be run once when the system is firststarted There is only one users admin in a system since it has system administrator like privileges You can change the admin s password later with the legion passwd command if you wish l user id LOID gt p lt password gt Allows userto log in to the Legion system as a user and sets up implicit parameters and security credentials for the user Note that the command can be run withoutany arguments although it will promptfor a user name if a user LOID or user id is not given User names are context names for AuthenticationO bjects special objects that contain a user password initial implicit parameters and other information created with the 1egion create user command Ona successful login a credentials file a user read only file is created in your local tmp directory The user s shell must be able to see this file sothathis hercommand line utilities can use it The file willbe removed when the user logs out with 1egion logout below You get a separate credentials file for each shell in which you run legion login The following options are supported p password Enter the password from the command line This method is not secure debug Catch and print Legion exceptions help Print command syntax and exit Thi
64. your Legion tty object Multiple IN in OUT out and CONSTANT constant files may be specified one per line The second field is the name of an inputor outputfile that your program expects to read or write to in the local directory of whichever hostit runs on The third field is the naming pattern for input and output files You may use as a pattern holder for IN in and OUT out files The pattern holder allows you to specify large groups of files in different directories for input and output For example suppose that you want to run program Foo Foo needs two input files FooFoo and MyFoo and a password It also produces one output file Bar Your specification file would look like this Reference June 19 2001 Legion 1 7 Reference Manual IN FooFoo mylocaldir foo ent in MyFoo mycontext bar gif OUT Bar mylocaldir output stuff CONSTANT secret etc passwd Legion looks in local space for files that fit the specified patterns and finds five sets of files IN LOCAL SPACE IN CONTEXT SPACE mylocaldir fool ent mycontext barl gif mylocaldir foo2 ent mycontext bar2 gif mylocaldir foo3 ent mycontext bar3 gif mylocaldir foo4 ent mycontext barA gif mylocaldir foo5 ent mycontext barB gif Notice thatthe firstthree files in each column have common patterns 1 2 and 3 whereas the last two do not 4 and 5 A and B The files with mismatched patterns are discarded leaving three s
65. 1 7 Reference Manual 8 3 Legion context space The following section provides a C interface to Legion context space int ContextSpaceActive Determines whether or not a valid context space exists Parameters None Return Values 0 if Context space is NOT active 1 if Context space is active User Responsibility None ContextLookup char LookupPath Look up the LOID of a name in the current context does not allow paths in the name Parameters Context name of an objectto lookup in the current context Return Values LOID of the object indicated context space Error Return NULL User Responsibility The user is responsible for free ing the LOID return value char ContextPathLookup char LookupPath Look up the LOID of the object named in the given Unix like context path This command will allow both absolute and relative naming Parameters context path name of an objectto lookup in context space Return Values LOID of the object indicated context space Error Return NULL User Responsibility The user is responsible for free ing the LOID return value Reference page 147 J une 19 2001 Legion 1 7 Reference Manual char ContextMultiLookup char LkupPath Look up the LOIDs of a number of objects named in the current context not path specified however Its somewhat confusing as to why this command takes a string at all but the string basically needs to contain as its parameter P
66. 2001 Legion 1 7 Reference Manual 8 10 Class object The following section contains a set of functions which interface directly with Class objects int Addimplementation LegionldType ClaType char ClassName LegionldType lldType char ImplName int Arch Adds a new implementation of a class binary to the given class Parameters CldType A flag indicating whether ClassName is a LOID ora context path ClassName The name of the class to add the implementation to IIdType A flag indicating whether ImplName is a LOID or a context path ImpIName The name of an implementation object to add Arch The architecture for which the implementation is valid Return Values 1 on Success 0 on Failure User Responsibility None int Deletelnstance LegionidType CldType char ClassName LegionldType lldType char InstanceNm Asks a class to delete one of its instances Parameters CldType A flag indicating whether ClassName is a LOID ora context path ClassName The name of the class to delete the instance from IIdType A flag indicating whether InstanceNm is a LOID ora context path InstanceNm The name of an object instance to delete Return Values 1 on Success 0 on Failure User Responsibility None Reference page 189 J une 19 2001 Legion 1 7 Reference Manual int Activatelnstance egionldType CldType char ClassName CInstancePlacementinfo Cinfo Asks a class to activate one of its instances
67. A GA SC H607305A J une 19 2001 Legion 1 7 Reference Manual Before you start 1 0 Introduction 5 1 1 About this manual 223 6 onu red Spese ec RE en RU ru 5 1 2 Siyle conventiohiS oc pretation Kite ees OU E Ober ee ind 5 Legion commands 2 0 Command line functions 7 2 1 Calls om objects 244 055 no tirrenia tee eee eee ia EIS 7 2 2 CallS oriclass ODIGCUS 1 on adn a 3 hide Vaca abd s e nts 14 2 3 Calls on LegionClass 2421s beni eeauk ie riG4 E Une Ren oh 22 2 4 Calls on file and context objects cece eee ees 26 2 5 Start up and shutdown functions 00 e eee ees 38 2 6 Scheduling SUPDOM i rry seein LER S bee cia ie EE OSEE 45 2 7 General functions about the state of the system 57 2 8 SBCHPND emu v aa pea a a a SUR MONA bea nary wen oa 62 2 9 Application development 12 2 ool y y RE 73 2 10 Program su DOT usos tite spat ae deque Gc nt doctae fo ferio saut tds 80 3 0 Error codes 115 4 0 Internal tools 117 Manipulating hosts and vaults 5 0 Alternative ways to start and shut down 119 5 1 Starting extra hosts and vaults command line 119 5 2 Shutting down extra hosts and vaults command line 120 bi3 Restarting extra hosts and vaults 0 cece eee 120 5 4 Using two hosts to startup a system cece eee eee 120 Runtime library examples and interfaces 6 0 Example translations the simple class 122 6 1 Simple h and Simple C iude Mex e eR athe eR Rado
68. D ContextR emove ContextS ingleR everseLookup ContextS paceActive legion_cd legion_mkdir exceptions interface Legion ExceptionCatcherDefaultE nable host objects CancelHostR eservation ChangeObjectO wner CheckHostR eservation GetC ompatibileV aults GetlmplArchF romHost GetlmplementationCache GetObjectStatus HostDeactivateO bject KillO bject ListO bjects MakeR eservationF romHost VaultOK implicit parameters MessagelmplicitParm FindInt MessagelmplicitP arm_FindLOID MessagelmplicitP arm_FindString MessagelmplicitP arm_Insertint MessagelmplicitP arm InsertLOID 179 177 177 141 190 189 190 189 190 191 141 199 199 200 201 200 149 147 148 150 149 147 148 150 151 149 150 147 152 151 146 181 185 181 183 181 184 184 182 182 183 180 183 197 196 197 195 195 Reference Legion 1 7 Reference Manual page 209 J une 19 2001 Legion 1 7 Reference Manual MessagelmplicitP arm_InsertS tring 196 MessagelmplicitP arm_Remove 196 MessagelmplicitP arm Replacelnt 198 MessagelmplicitP arm ReplaceLOID 197 MessagelmplicitP arm ReplaceString 198 MethodlmplicitP arm FindlInt 193 MethodlmplicitP arm FindLOID 193 MethodlmplicitP arm F indS tring 193 MethodlmplicitP arm InsertInt 192 MethodlmplicitP arm InsertLOID 191 MethodlmplicitParm InsertString 192 MethodImplicitP arm Remove 192 MethodlmplicitP arm Replacelnt 194 MethodImp
69. Legion 1 8 Reference M anual The Legion Group Department of Computer Science School of Engineering amp Applied Science University of Virginia 151 Engineer s Way P O Box 400740 Charlottesville VA 22904 4740 legion virginia edu http legion virginia edu Copyright 1993 2001 by the Rector and Visitors of the University of Virginia All rights reserved Permission is granted to copy and distribute this manual so long as this copyright page accompanies any copies The Legion system software herein described is intended for research and is available free of charge for that purpose Permission is not granted for distributing the Legion system software outside of your site In no event shall the University of Virginia be liable to any party for direct indirect special incidental or consequential damages arising out of the use of the Legion system software and its documentation The University of Virginia specifically disclaims any warranties including but not limited to the implied warranties of merchantability and fitness for a particular purpose The software provided hereunder is on an as is basis and the University of Virginia has no obligation to provide maintenance support updates enhancements or modifications This work partially supported by DARPA Navy contract 4 N66001 96 C 8527 DOE grant DE FD02 96ER25290 DOE contract Sandia LD 9391 Northrup Grumman for the DoD HPCMOD PET program DOE D459000 16 3C and DARP
70. Manual Third call z A opl x y Both parameters are values yet to be computed so they must be invocation parameters UVaL_Reference lt LegionInvocation gt inv3 inv3 A handle invoke SIMPLE OP2 FUNCTION NUMBER 2 3 G add invocation inv3 G add invocation parameter inv3 invl 1 UVaL METHOD R G add invocation parameter inv3 inv2 2 UVaL METHOD RETURN VALUE T URN VALUE We specifically ask for the in out parameters Don t get them otherwis G add result dependency inv3 1 G add result dependency inv3 2 printf dNn z We need z so we must execute G execute and wait for the return UVaL_Reference lt LegionBuffer gt lb lb G get value inv3 UVaL METHOD RETURN VALUI lb get int amp z 1 printf z is dWMn z LH Since we asked for them we can get the other values too G release all values lb G get value inv3 1 lb get int amp x 1 printf x is d n x lb G get value inv3 2 lb gt get_int amp y 1 printf y is d n y Legion DestroyObject A name Legion DestroyObject B name Reference page 129 J une 19 2001 Legion 1 7 Reference Manual 7 0 Interfaces Below are selected parts of the interface from selected objects that make up the Legion Library implementation 7 1 LegionProgramGraph UVaL Reference Leg
71. Name Find an implicit parameter in the implicit method parameters database this parm must be an int parameter Parameters ParmName The name of the implicit parameter to which the action is being applied Return Values The integer parameter that was retrieved from the database Error Return Need to check LegionE rrno for this one UserResponsibility None char MethodlmplicitParm FindString char ParmName Retrieve a string parameter from the implicit method parameter database Parameters ParmName The name of the implicit parameter to which the action is being applied Reference page 193 J une 19 2001 Legion 1 7 Reference Manual Return Values The string parameter retrieved from the implicit method database Error Return NULL User Responsibility The user is responsible for free ing the memory returned from this function call int MethodlmplicitParm ReplaceLOID char ParmName char Loid Replace an implicit method parameter in the database with another LOID parameter Parameters ParmName 2 The name of the implicit parameter to which the action is being applied Loid The LOID parameter to replace ParmName With Return Values 0 on Failure 1 on Success User Responsibility None int MethodlmplicitParm Replacelnt char ParmName int Value Replace an implicit method parameter in the database with another int parameter Parameters ParmName The name of the implici
72. OPR gt A lt SLEGION_ARCH gt N lt context name gt U user id C vault class debug help Legion 1 7 Reference Manual Specify LEGION for the vaults host Default is the local LEGION value Specify LEGION_OPR for the vaults host Default is the local LEGION_OPR value Specify the architecture of the vaults host Default is the local LEGION_ARCH value Specify the context name for the vault object Defaultis vaults vault host name Specify the user id to use on the vaults host Default is current user id S pecify the vaultobject s context path default is class UnixVaultClass Catch and print Legion exceptions Print command syntax and exit Reference June 19 2001 2 6 legion cl Legion 1 7 Reference Manual S cheduling support add sub collection collection LOID gt c collection path member LOID c member path q lt query gt This command creates a new parent subcollection relationship A subcollection is a collection objectthatis polled by another collection object called the parent collection with a specified MESSIAHS type query see 1egion query collection page 51 for details If no query is specified the default value of true will be used You can run this command multiple times to start multiple queries on a single subcollection A parent collection can have more than one subcollection and can run multipl
73. OW a Oo eZ aw v CO lt bool expression gt true TRUE True false FALSE False lt comparison expr gt lt expr gt lt expr gt lt expr gt lt lt expr gt lt expr gt gt lt expr gt expr lt expr gt expr lt expr gt expr expr expr expr lt expr gt or lt expr gt expr xor lt expr gt expr and lt expr gt not lt expr gt match lt string gt lt string gt lt comparison expr gt lt int const gt lt oct const gt lt float const gt 5 This paper is available on line at lt http legion virginia edu papers_abstracts html messiahs gt Reference page 51 June 19 2001 page 52 Legion 1 7 Reference Manual string identifier a w eZ lt expr gt eZ lt expr gt eZ lt expr gt expr eZ expr lt expr gt eA max lt expr gt lt expr gt min lt expr gt lt expr gt eZ lt expr gt lt expr gt e expr lt expr gt eZ expr mod lt expr gt eZ int lt expr gt float lt expr gt lt expr gt lt int const gt __any valid integer constant__ lt oct const gt o 0 7 lt float const gt __any valid float constant__ lt string gt E lt identifier gt a zA Z Variables are ofthe form VAR NAME e g system arch The official variable names will be those exported by resource objects in their
74. Reference page 25 J une 19 2001 Legion 1 7 Reference Manual 2 4 Calls on file and context objects legion activate instances c class context name 1 class LOID gt debug help Activates all instances ofthe class named in c1ass context path Or class LOID gt Instances thatare already active will be unaffected The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion allow activation entire class debug help c context path 1 lt LOID gt Activates the object or instances of the class named in context path or lt LOID gt It should be used in association with the stay down option of legion deactivate object or legion deactivate instances page 16 and page 29 respectively The following options are supported entire class Unlock all ofthe class s instances You mustbe the class s owner in order to use this option debug Catch and print Legion exceptions help Print command syntax and exit legion_cat context pathl context path2 gt context pathN gt debug help legion cd Prints the contents of the Legion file object s named in context path to standard output It is similar to the Unix cat command legion cat newFileObject blah blah blah The following options are supported debug Catch and print Legion exceptions help Print command syntax and
75. This file contains a list of Unix user ids and any corresponding Legion user ids If no Legion account is named the account will be treated as a guestaccount There is no limit on the number of mappings that can be listed A sample mapping file is below guest unixLucy c users lucy unixJohn c users john legion create class c context path gt sc scheduler context path gt sl scheduler LOID gt debug help page 38 Creates a new instance of VanillaMetaClass The new class will be placed in the current working context unless you specify otherwise The following options are supported Reference June 19 2001 legion destroy host v c host Legion 1 7 Reference Manual c context path Assigns the context name in context path to the new instance sc scheduler context path Specify the context path of the default scheduler object that the new class should use sl scheduler LOID Specify the LOID of the default scheduler object that the new class should use debug Catch and print Legion exceptions help Print command syntax and exit context path 1 host LOID gt debug help Destroy a given host object All contexts objects on that host will be destroyed and all active objects will be deactivated Legion will automatically search your context space and remove any dangling context names for the host object Optional parameters do the following
76. Type IdType char ObjName Determines if the indicated objectis a context object or not Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to test Return Values 1 if the object is a context 0 if the object is nota context User Responsibility None int isFile LegionldType ldType char ObjName Determines if the indicated objectis a File objector not Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the objectto test Return Values lifthe objectisaFile 0 if the objectis nota File User Responsibility None int isRunnable LegionldType IdType char ObjName Determines if the indicated object is a Runnable object or not Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName Either the context path name or the LOID of the object to test page 164 Reference J une 19 2001 Legion 1 7 Reference Manual Return Values lifthe objectis a Runnable 0 ifthe objectis nota Runnable User Responsibility None int isClass LegionldType IdType char ObjName Determines if the indicated object is a Class object or not Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to test Return Values
77. WorkUnit next matched Parameters None Returns the next work unit The priority scheme is obeyed UVaL_Reference lt LegionWorkUnit gt next matched for func Parameters intfunc num Return the next work unit with the given function number int set priority Parameters int func num int priority Setthe priority for the given function number int insert Parameters UVaL_Reference lt LegionWorkUnit gt new work unit Insert the provided work unit into the invocation store This work unit may be a method request or it may be a result from a previous method invocation Reference page 131 J une 19 2001 Legion 1 7 Reference Manual UVaL ReferencecLegionWorkUnit get return value Parameters UVaL_Reference lt LegionComputationTag gt tag int parameter_number Returns the work unit with the given tag and parameter number Typically this function is called by a higher layer e g LegionProgramGraph which will unwrap the returned work unit to get the parameter inside int release_return_value Parameters UVaL_Reference lt LegionComputationTag gt tag int parameter_number Deletes the work unit that matches the supplied tag parameter_number pair int release_all_return_values Parameters None Deletes all return values from the invocation store 7 3 LegionWorkUnit int get function number Parameters None Returns the target function number for the work unit UVaL_Reference lt LegionContinuationList gt
78. a 2D file object Reference page 37 J une 19 2001 Legion 1 7 Reference Manual 2 5 Start up and shutdown functions legion add host account l host object LOID gt c lt host object context path gt f mapping file name gt lt Unix user id gt debug help l owner LOID gt c owner context path gt This command is used on PCD hostobjects Adds a mapping between a Legion account and a Unix account and adds this mapping to a PCD hostobject s listof available accounts The user s Unix userid is named in the Unix user id parameter The host object is named in the lt host object LOID gt lt host object context path gt parameter The user s Legion user id can be given in the lt owner LOID gt lt owner context path gt parameter or listed in the mapping file The following options are supported f mapping file name Names a mapping file The mapping file contains a list of Unix user id Legion user name mappings for that PCD host object There is no limit on the number of mappings that can be listed One mapping per line If a Unix id is listed butnot mapped to a Legion user id the account will be a guest account debug Catch and print Legion exceptions help Print command syntax and exit There are two ways to add host accounts directly from the command line or via the flag with a mapping file A mapping file contains a list of Unix Legion account mappings
79. a context path name ObjName The context path name or the LOID of the object to test Return Values 1 if the object is a Implementation 0 if the object is nota Implementation User Responsibility None int islmplementationCache egionldType IdType char ObjName Determines if the indicated object is a ImplementationCache object or not Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to test Return Values 1 if the object is a ImplementationC ache 0 if the object is nota ImplementationCache page 166 Reference J une 19 2001 Legion 1 7 Reference Manual User Responsibility None int isLegionClass LegionldType IdType char ObjName Determines if the indicated objectis a LegionClass objector not Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to test Return Values 1 if the object is a LegionClass 0 if the object is nota LegionClass User Responsibility None int isBindingAgent LegionldType ldType char ObjName Determines if the indicated object is a BindingAgent object or not Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to test Return Values lifthe objectis a BindingAgent 0 if the objectis no
80. ade Parameters HIdType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host that will check the reservation HstRes The previously made host reservation Return Values A CLegionHostR eservationR ecord containing the status of the reservation Error Return 0 User Responsibility User is responsible for destroying the host reservation record when done int CancelHostReservation LegionldType HldType char HostName CLegionHostReservation HstRes Cancel a previously made host reservation Parameters HidType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host that will cancel the reservation HstRes The previously made host reservation Return Values 1 on Success 0 on Failure User Responsibility None int GetlmplArchFromHost LegionldType HidType char HostName Retrieve the implementation architecture for a given host Parameters HIdType A flag indicating whether HostName is a context path name or a LOID HostName The name of the hostto getthe arch from Reference page 181 J une 19 2001 Legion 1 7 Reference Manual Return Values The architecture of the given host Error Return 1 User Responsibility None int KillObject LegionldType HidType char HostName CLegionBinding binding int actld Kill an object running on a host Parameters HidType A flag indicating whether HostName is
81. ag indicating whether the ClassName parameter is a context path name or a LOID ClassName LOID or context path name of the class to instantiate HIdType Flag indicating whether the HostName parameter is a context path name or a LOID HostName LOID or context path name of the Host to which the instantiation is restricted VidType Flag indicating whether the HostName parameter is a context path name or a LOID VaultName LOID or context path name of the Vault to which the instantiation is restricted IIdType Flag indicating whether the HostName parameter is a context path name or a LOID ImplName LOID or context path name of the implementation to which the instantiation is restricted Return Values NULL terminated array of LOIDs indicating the objects that were instantiated Each elementofthe array is a char which is the LOID of one object created page 154 Reference J une 19 2001 Legion 1 7 Reference Manual Error Return NULL User Responsibility User is responsible for free ing each LOID in the array as well as the array itself char ScheduledCreateRestricted int NumObjects LegionldType CIDType char ClassName LegionldType HIDType char HostName LegionldType VIDType char VaultName LegionldType IIDType char ImplName LegionldType SIDType char SchedName Create a vector of new Legion objects by vector instantiating the given class The user also indicates any combination of rest
82. also shuts off the background legion_tty_watch process for the current shell Reference page 35 June 19 2001 Legion 1 7 Reference Manual legion tty redirect This command only works on tty objects that have been set with the legion ttycommand See legion tty watchforinformation on turning off other tty objects Please see page 75 in the Basic User Manual for a discussion of tty objects Note thatthis does notdestroy the tty object The object can be reused with iegion tty legion set tty Orlegion tty watch The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit object context path debug help Causes the Legion tty object currently set in the shell environment to stream directly into the file objectnamed in object context path Ifthe file does notalready existthe system creates it E xisting files are appended to nottruncated A single tty object can be simultaneously directed into any number of files as well as watched from any number of terminal windows P lease see page 75 in the Basic User Manual for a discussion of tty objects The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_tty_unredirect lt object context path gt debug help Causes the Legion tty object currently set in the shell environment to stop streaming into the file objectnamed in l
83. arameters Unclear but give it Return Values NULL terminated array of context space names for objects in the indicated context In other words each element of the array is a char which is either the context name of an object or NULL if itis the end ofthe list Error Return NULL User Responsibility The useris responsible for free ing each non NULL entry in the array as well as the array itself char ContextPathMultiLookup char LkupPath Look up the LOIDs of a number of objects named in a Unix like context path absolute or relative path names are perfectly valid here Its somewhat confusing as to what the parameter to this command means Basically the thing to do here is to indicate the context path you wanta listing for and append and to it Parameters Unclear but basically the path you want a listing of with appended to it l e if you wanta listing of home mark the parameter should be home mark NOTE in the above paragraph there are spaces between and thatshould be removed These are there to keep the C compiler from thinking we are commenting Return Values NULL terminated array of context space names for objects in the indicated context In other words each element of the array is a char which is either the context name of an object or NULL if itis the end ofthe list Error Return NULL page 148 Reference J une 19 2001 Legion 1 7 Reference Manual User R
84. ate Return Values 1 on Success 0 on Failure User Responsibility None CUVaL InstanceRecord GetlnstanceList Legionld Type CldType char ClassName Asks a class to return a list of all of the instances that it is currently managing Parameters CldType A flag indicating whether ClassName is a LOID ora context path ClassName The name of the class to retrieve the list from Return Values A NULL terminated list of CUVaL_InstanceRecords where each element in the array is the UVaL_InstanceRecord for one of the objects that the class is managing Error Return NULL User Responsibility The user is responsible for destroying each CUVaL InstanceRecord in the list as well as for free ing the list itself 8 11 Legion implicit parameters The following section contains the functions which allow a program to manipulate its own method and message implicit parameters int MethodlImplicitParm InsertLOID char ParmName char Loid Insert a LOID implicit parameter into the Implicit method parameters Parameters Reference page 191 J une 19 2001 Legion 1 7 Reference Manual ParmName The name of the implicit parameter to which the action is being applied Loid The String representation of the LOID to add Return Values 0 on Failure 1 on Success User Responsibility None int MethodlmplicitParm InsertInt char ParmName int Value Insert an int implicit parameter into the Implicit method parameter
85. ath name of the Scheduler to use when doing the activation Return Values 1 on Success 0 on failure User Responsibility None int ComplxActivateRestricted LegionldType OIDType char ObjectName LegionldType HIDType char HostName LegionldType VIDType char VaultName LegionldType IIDType char ImplName Activate an inert Legion object but subject to the restrictions indicated by the user Parameters OIlDType Flag indicating whether the ObjectName parameter is a context path name or a LOID ObjectName LOID or context path name of the object to activate HIdType Flag indicating whether the HostName parameter is a list of context path names or LOIDs HostName ANULL terminated array of LOIDs or context path names of Hosts to which the activation is restricted VidType Flag indicating whether the VaultName parameter is a list of context path names or LOIDs VaultName A NULL terminated array of LOIDs or context path names of Vaults to which the activation is restricted page 160 Reference J une 19 2001 Legion 1 7 Reference Manual IIdType Flag indicating whether the lImplName parameter is a list of context path names or LOIDs ImpleName A NULL terminated array of LOIDs or context path names of Implementations to which the activation is restricted Return Values 1 on Success 0 on failure User Responsibility None int ComplxScheduledActivateRestricted LegionldType OIDType char O
86. be joined to one another to form a single system The command is implemented this way to avoid communication failures if a LOID can be passed to an object e g in a method continuation list thatobjectshould be able to use the LOID for further communication Non transitive or non reflexive joins would allow communication of LOIDs for which an object could not obtain a binding For example objectX in domain A might be able to bind to objectY in domain B and pass a method to it but object Y might not be able to bind to object X to pass itthe return value In addition to joining the binding trees of the involved domains legion combine domains also creates context links in the current domain s context space to all of the remote domains root contexts These links appear in local context space in the following path domain LegionDomain lt domain id gt Ifthe command is run on domains that are already connected ithas no affect and is harmless There is currently no mechanism supporting unjoining of domains However Legion security mechanisms e g ACLs can be used to effectively forbid any use of the current domain by outside domains The following options are supported v P rovide a verbose output as the command is running debug Catch and print Legion exceptions help Print command syntax and exit page 22 Reference June 19 2001 Legion 1 7 Reference Manual The example below combines two domains If either had previo
87. bjectName LegionldType HIDType char HostName LegionldType VIDType char VaultName LegionldType IIDType char ImplName LegionldType SIDType char SchedName Activate an inert Legion object but subject to the restrictions indicated by the user and using the given scheduler Parameters OIDType Flag indicating whether the ObjectName parameter is a context path name or a LOID ObjectName LOID or context path name of the object to activate HIdType Flag indicating whether the HostName parameter is a list of context path names or LOIDs HostName ANULL terminated array of LOIDs or context path names of Hosts to which the activation is restricted VidType Flag indicating whether the VaultName parameter is a list of context path names or LOIDs VaultName A NULL terminated array of LOIDs or context path names of Vaults to which the activation is restricted IldType Flag indicating whether the ImplName parameter is a list of context path names or LOIDs ImpleName A NULL terminated array of LOIDs or context path names of Implementations to which the activation is restricted SIDType A flag indicating whether the SchedName parameter is a context path name or a LOID SchedName A context path name or LOID indicating the scheduler to use when doing the activation Reference page 161 J une 19 2001 Legion 1 7 Reference Manual Return Values 1 on Success 0 on failure User Responsibility None int
88. by Legion objects and are not intended to be run from the command line legion accounting info pusher Used by the host object to push accounting information back to the legion get accounting info tool page 57 It is only used by the host object legion init Apps security Start the Application package s security This command is automatically run when you run 1egion init Apps page 67 legion init Extra security Start the E xtra package s security This command is automatically run when you run legion init Extra page 67 legion init HPC security Startthe HPC package s security This command is automatically run when you run 1egion init HPC page 67 legion init SDK Initiate the SDK package This command is automatically run when you run legion initialize page 39 legion init SDK security Startthe SDK package s security This command is automatically run when you run 1egion init security page 67 legion make backend Backend scriptfor legion_make page 73 The Legion admin installs this tool as a class usually in contextspace in class class HPC or class SDK Installed using 1egion register program legion modify scheduler Used to configure any instance of the round robin scheduler Used to setthe hosts from which the scheduler will selecttargets the collection from which it gets its info and so on legion mplfront This toolis the actual binary forthe Legion MPLC compilerandis called
89. c lt class context path 1 class LOID gt a d t lt vault1 gt lt vault2 gt lt vaultn gt p debug help page 46 Manipulates the list of vaults upon which the class named in c1ass context path Ol class LOID gt can place its instances OPRs Note that if you identify the class by its context name in the first parameter i e myClass you must use context names in the lt vault1 gt lt vault2 gt lt vaultn gt parameter Similarly if you use a LOID with the 1 flag you must use LOIDs Optional parameters are 1 Use LOIDs to specify class and vault a Add named vaultto the class s acceptable vault list d Delete named vault from the class s acceptable vault list t Test whether or not a vault is on the class s acceptable vault list Reference June 19 2001 Legion 1 7 Reference Manual p Display the class s acceptable vault list debug Catch and print Legion exceptions help Print command syntax and exit Youcanusethe a a and t flags more than once when running the command but regardless of how you list them on the command line Legion will process themin a specific order when you run the command first adding any new vaults then deleting old vaults then testing any vaults and finally printing outthe results legion config scheduler c scheduler context path get enactor get collection set enactor c lt enactor context path 1 enactor LOID gt
90. cal machine Your local machine must have access to a working Legion net Please note that you must also run 1nfsd below in order to start an Legion NFS session Currently the Legion NFS mount daemon only works on Linux and Alpha Linux platforms Please contact us at lt legion help cs virginia edu gt if you need to run iton another architecture Legion context space is mounted via the same means used to mount a normal NFS file system i e mount When you NFS mount context Space 1mountd checks your MOUNT request against your local exports file the list of exported file systems If your machine is listed lmountd creates and returns a file handle and adds an entry in etc rmtab To end the session run umount Upon receipt of your UMOUNT request 1mountd removes your client s entry from rmtab The client kernel unmounts the file system Please note thata Legion NFS mount does not give you permission to view or use Legion objects if your Legion system requires a Legion login you must run 1egion login page 68 as a separate step The 1mountd should be run locally Please read the Security and Example sections of the rpc 1nfsd command page 111 E xports file The exports file contains a list of what file systems are available for export and which machines are allowed to mount those file systems The 1mountd reads the root of context space as 1egion so it will listed in the exports file in the following format legion
91. ccess to a MySQL database whose scheme has been configured for Legion accounting information e Msql Mysql modules and Data Dumper Perl modules installed The tool may attempt to perform reverse context lookups on object LOIDs in order to determine human readable identifiers i e context paths Forsuitable results we suggestthatyou only run this command if you are logged in as users admin You must include the following parameters local configuration file path A local text file that contains database configuration information in this format client host database users password lt local logfile directory gt A local directory that contains accounting information logs The following option is supported v Run in verbose mode Print information about which log requests the command is currently working on legion_update_stat_tree v help t lt repeat delay seconds gt site top site context path gt collection collection context path gt Updates a database ofcurrentloads on all hostobjects in a system You can setthe command to run at regular intervals The following options are supported v Verbose mode help Print this help message and exit t Specify that the command should operate in continuous mode continually updating the stat tree every repeat delay seconds seconds Use ctr1 C to quit out of continuous mode site site context path Specify the top level con
92. ch LOID in the array as well as the array itself char ComplxCreateRestricted int NumObjects LegionldType CIDType char ClassName LegionldType HIDType char HostName LegionldType VIDType char VaultName LegionldType IIDType char ImplName Create a vector of new Legion objects by vector instantiating the given class The user also indicates any combination of restrictions which may include restrictions to hosts vaults or implementations Parameters NumO bjects 2 Number of object to vector instantiate CldType Flag indicating whether the ClassName parameter is a context path name or a LOID ClassName LOID or context path name of the class to instantiate HIdType Flag indicating whether the HostName parameter is a NULL terminated list of context path names ora NULL terminated list of LOIDs HostName NULL terminated array of LOIDs or context path names of the Hosts to which the instantiation is limited VidType Flag indicating whether the VaultName parameter is a NULL terminated list of context path names ora NULL terminated list of LOIDs VaultName NULL terminated array of LOIDs or context path names of the Vaults to which the instantiation is restricted IIdType Flag indicating whether the ImplName parameter is a NULL terminated list of context path names ora NULL terminated list of LOIDs ImpIName NULL terminated array of LOIDs or context path names of the Impls to which the instantiation is r
93. ch and print Legion exceptions help Print command syntax and exit Reference page 79 J une 19 2001 Legion 1 7 Reference Manual 2 10 Program support legion ft initialize This is a scriptthatinitializes the CheckpointStorage object This object is used by MPI faulttolerance implementation and must be run before you can use the 1egion mpi run fault tolerant flags page 90 You only need to run it once however legion FTPd help v p port number gt a m max connections gt t transfer block size gt o max outstanding invocations gt d w e rt RMI timeout gt dt detail timeout gt Starts the Legion FTP daemon from the command line This daemon is a Legion enabled server tool for accessing Legion context space via FTP Once you ve started the daemon you can use a standard FTP client software to view store and retrieve objects from your context space Once started the daemon s operating parameters cannotbe changed To terminate send a SIGINT or c signal Please be aware that if you use the a flag other users will be able to use your daemon to view and use your context space Your password will also travel in the clear over the network The Legion FTP daemon will only work for systems running Legion version 1 7 or higher Itimplements the minimum requirements of an FTP server as outlined in RFC 959 and RFC 1123 The following options are supported help Print the usage in
94. change_permissions v lt group user context path rwx lt target context path gt debug page 64 help Changes an object s read write and execute permissions so that you can allow the user or group named in lt group user context path to use the object named in target context path This tool manipulates an object s access control list ACL so that other users can call methods on your objects For our purposes read methods are defined as methods that obtain but do not modify an object s state write methods are methods that modify an object s state and execute methods are methods thatrun an object For example giving bob read permissions for object foo below lets him view but not alter oo s state legion change permissions r users bob foo This command works on common Legion object types context file class tty implementation host and vault objects all fall into this category The following optional parameters are supported r Deny read permissions to the target object r Grant read permissions to the target object w Deny write permissions to the target object w Grant write permissions to the target object x Deny execute permissions to the target object this option is for class objects only Reference June 19 2001 legion create user a admin path gt Legion 1 7 Reference Manual x Grant execute permissions to the target object this optio
95. class context path Or class LOID The hostfile is printed to stdout The output of 1egion make schedule may be redirected into a file and used with the F flag in 1egion mpi run see page 85 The following options are supported n number of nodes S pecify the number of nodes required for this run Defaultis 1 f lt specification file gt Name a Specification file that contains relative performance ratios for different architectures E g the specification file could contain the lines linux 1 alpha_linux1 5 solaris 0 7 Reference June 19 2001 q query help legion_query_collection v tpe debug help Legion 1 7 Reference Manual Specify a MESSIAHS query interface described below in 1egion query collection that can be used to prune the list of hosts on which the run can be scheduled P rint command syntax and exit Collection context path Collection LOID gt query This command searches for information ofthe collection object named in collection LOID Or collection path gt The formatofthe query string is described in the paper Constructing Distributed Schedulers Using the MESSIAHS Interface Language by Steve J Chapin and Eugene H Spafford Collection queries can be constructed using the interface below query lt bool expression gt x e x eZ comparison expr lt expr gt Q OQ v Oo OQ O amp O OG
96. ctionality the CError h header file contains all necessary declarations to doing some small amountof error handling Legion 1 7 Reference Manual Change Log ifndef CLEGION_ define CLEGION_ extern C endif ifdef _ cplusplus include lt stdio h gt IB H IB H Bii Note that anytime this header file talks about freeing memory it is referring to using the C language s free function to return memory to the heap NOT the C language s delete operators LOID Parameters define LOID PARAM define CONTI typedef Cypec Cypec Cypec type type type type type type CyYpeada o Q0 20 Q Q 000 00000 00 0 lt ko o Q EXT PARAM int in in in asm in in in in in in CE xtd Gh er IGE 2ER ch ck ct in L QAO OOOO AAO egionIdType LegionBinding LegionHostReservation LegionHostReservationRecord LegionVaultReservation LegionReservation LegionHostObjectStatus LegionOPRAddress UVaL_InstanceRecord InstancePlacementInfo LegionCollection Data Reference LegionVaultReservationRecord These defines give th X two valid values for LegionIdType variables xy parameters ey This type is usedin function calls to indicate yr whether or note the parameter is a LOID The E valid values are LOID_PARAM and CONTEXT PARAM These typedefs are used to
97. ctory it will eventually be tarred and moved One of the following parameters must be used p robe lt local file name The name of the local probe file associated with the desired job 1 lt probe LOID gt The probe s LOID may not be supported in all releases The following options are supported Options may be repeated The order of specified options except v erbose debug help and p robe determines order in which tasks will be done debug Catch and print Legion exceptions help Print command syntax and exit v erbose Run command in verbose mode in lt context path name gt Context path of a Legion file object whose contents should be copied into the remote program s current working directory The local file will have the same name as the context path name basename Reference June 19 2001 Legion 1 7 Reference Manual out context path name Context path of a Legion file object IN local file name gt OUT local file name whose contents should be copied out of the remote program s current working directory If the file doesn t exist you will getan error message The local source file will have the same name as the context path name basename Output files that are not found in the program s current working directory are skipped Similar to the in option but oper ates on a file in legion probe run s local exe cution environment i e the file name
98. d and write untyped characters from and to a logical buffer These operations are also exported by LegionBuffer but the user should be warned that the better way to put data into a buffer is through the LegionPacker interface read and write will not perform appropriate data format conversions but put_int and get int Will size_t read Parameters size_t num_bytes void data Reads num_bytes bytes from the buffer starting at the current location of the buffer pointer Copies the bytes into the space pointed to by data_dest Returns the number of bytes actually read and positions the buffer pointer immediately after the last byte that was read Read will not read past the end of the buffer size_t write Parameters size_t num_bytes void data Writes num_bytes bytes pointed to by data into the buffer Starting at current position of the buffer pointer overwriting existing data Returns the number of bytes actually written and positions the buffer pointer immediately after the last byte that was written Writing past the end of the buffer causes it to expand size_t seek Parameters seek_start whence int bytes_away Changes the position of the buffer pointer The whence parameter can be BEGINNING 0 CURRENT 1 0r END 2 and bytes away tells how many bytes away from whence to set the pointer Seeking past the end of the buffer causes it to Reference page 133 J une 19 2001 Legion 1 7 Reference Manual
99. d in 1ocal file name Similar to the out option but oper ates on a file in legion probe run s local exe cution environment i e the file named in 1ocal file name setscratch context path Specify which part of your context showscratch pwd hostname list stat remote file name gt space should be used as scratch space for this remote job Default is tmp Print the currently set context scratch space This will be the most recently specified space Print the remote job s present working directory This is useful if you set this directory with the a option when you ran 1egion run Print the remote host s DNS name Printa list of files in the remote job s current working directory Print the status of a particular file in the remote job s current working directory delete remote file name Delete the specified file from the statjob signal number kill Reference remote working directory Printa summary ofthe remote job s status Possible values are Running Error and Done Send a signal to remote job see kill 1 Kill the remote job if it hasn t yet terminated and clean up its remote page 97 June 19 2001 legion pvm register Legion 1 7 Reference Manual current working directory Please note that if you have not yet retrieved output files they will be lost If you started legion_run in nonblocking mode and you do notcl
100. d vault is unacceptable The class object will enforce the current restrictions on its instance s acceptable vaults before it migrates the object s state You may need to change the instance s list of acceptable vaults via the legion instance vault list command to include the target vault before running 1egion set vault This command is not exactly the equivalentofa true object migration since the object is not reactivated after its state is moved Where the objectreactivates depends onthe scheduling decision made atthetime the reactivation occurs If the permanent flag is not used and the Reference June 19 2001 legion synch vaults Legion 1 7 Reference Manual instance s acceptable vault list is not otherwise altered future activations of the instance may be on different vaults If permanent is used all future activations must use the specified vault until the acceptable vault list is altered c instance context path 1 instance LOID gt nodeac tivate S ynchronize the specified object s state in its main and backup vaults The command copies the state contained in the object s main vaultto all of its backup vaults It will deactivate the objectbefore synchronizing vault state unless the nodeactivate flag is used Ifthe objecthas been marked as Write Once Read Many WORM with the legion_set_worm command page 12 its state does not change Y ou can still run this command fora WORM object but it wil
101. e User Responsibility None int AddAttributes LegionldType ldType char ObjName char Attribute Add a list of attributes to an object s attribute database page 168 Reference J une 19 2001 Legion 1 7 Reference Manual Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to which the attribute will be added Attribute A NULL terminated list of the string representations of the attributes to add to the database These are of the form attribute signature attribute value Return Values 1 on Success 0 on Failure User Responsibility None int ReplaceAttribute LegionidType IdType char ObjName char OldAttribute char NewAttribute Replace an attribute in an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to which the attribute will be added OldAttribute The string representation of the old attribute to replace in the database This is ofthe form attribute signature attribute value NewAttribute The string representation ofthe new attribute to put into the database This is of the form attribute signature attribute value Return Values 1 on Success 0 on Failure User Responsibility None int ReplaceAttributeSig LegionldType IdType char ObjName char OldAttributeSig
102. e Manual The specified class must belong to the SKCC metaclass You must have previously set up the class s backup vaults with the legion skcc set class vaults command page 11 Currently BasicFileClass ContextClass ImplementationO bject and UserAuthenticationO bject are SKCC classes The following parameters must be used 1 lt SKCC class LOID gt Or c SKCC class context path S pecify an SKCC class object number of default vaults The maximum number of backup vaults that will hold copies of the SKCC class objects state legion unset worm c instance context path 1 instance LOID gt I This command tells Legion that the specified object has Write Once Read Many WORM semantics and can be used for caching and replicating purposes Itshould be used in conjunction with 1egion unset worm page 12 and legion set backup vaults page 18 This command tells Legion thatthe specified objectno long has Write Once Read Many WORM semantics It should be used in conjunction with 1egion set worm page 12 and legion set backup vaults page 18 legion update attributes c lt object context path 1 object LOID gt a new attribute d attribute r old attribute new attribute gt I S page 12 debug help Adds deletes and replaces an object s attributes The attribute s takes the form name vall valn The attribute description must not con
103. e copy constructor is also overloaded Accessor functions LegionParameter exports public member functions to get and set both the parameter number and the buffer containing the value of the parameter Overloaded operators The operator is overloaded to return 1 when the parameter numbers are the same and 0 otherwise show Parameters None Prints the contents of the LegionParameter to the stderr stream int pack int unpack Parameters LegionBuffer amp lb LegionParameter is packable 7 5 2 LegionP arameterList Constructors The default constructor creates an empty parameter list and a constructor that takes a LegionBuffer as an argument unpacks the contents of the LegionParameterList from that buffer Set operations LegionParameterList is derived from templated class UVaL_PackableSet_LinkedList and therefore exports the full interface of UVaL_PackableSet UVaL_Reference lt LegionParameter gt find Parameters int parameter_number Augments the Uvar Set operations to allow parameters to be looked up by number Returns a reference to the parameter if found or a null reference if not show Parameters None Prints the contents of the LegionParameterList to the stderr stream Reference page 139 J une 19 2001 Legion 1 7 Reference Manual int pack int unpack Parameters LegionBuffer amp lb LegionParameterList is packable 7 5 3 LegionComputationT ag LegionComputationTag simply maintains a g
104. e gt L lt SLEGION dir legion_print_config debug page 40 help name debug help Generates a Legion setup script for your system This script sets the environment variables for Legion users The following options are supported o lt script basename Specify the basename for the resulting setup scripts default is home xxxx OPR setup This command will generate two setup scripts for bin sh derivative users and csh derivative users The scripts will be named lt script basename gt sh and lt script basename gt csh respectively OPR OPR dir name gt Specify the OPR directory name that will be set up when the resulting scripts are run This directory will contain the user s local copy of Legion Class config default is Legion OPR The user s local version ofthe directory will be placed in the user s HOME L lt LEGION dir name Specify the value of LEGION which is the directory where the resulting scripts are run The defaultis the current value of LEGION debug Catch and print Legion exceptions help Print command syntax and exit Prints the well known binding for LegionClass in the current Legion configuration The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Reference J une 19 2001 Legion 1 7 Reference Manual legion remove host account 7 1 host object LOID gt c host object c
105. e queries on a single subcollection A subcollection can have more than one parent as well as its own subcollections You must designate a parent collection named in collection LOID gt Or collection path The member named in member LOID Or member path is the subcollection Both collections must already exist You can editthe col11ection update frequency secs attribute with the 1egion update attributes command page 12 The default setting is 300 seconds The example below will setthe default collection to update itself every 10 minutes legion update attributes c etc Collection collection update frequency secs 600 The following option is supported q query A MESSIAHS style query that will be run on the subcollection The default selection is true See legion query collection page 51 for details legion class host list c class context name gt 1 lt class LOID gt a d t hosti host2 lt hostn gt p debug help Manipulates the list of hosts upon which the class named in c1ass context path Or class LOID gt can place its instances The list of acceptable hosts fora given class consists only of hosts thathave been added to the list The list therefore may not necessarily include all possible hosts If there are no hosts listed as acceptable the user can assume that all hosts are acceptable Note also that if you identify
106. e vault with Binding The object in question s binding Return Values The Objects status User Responsibility None char GetlmplementationCache egionldType HidType char HostName Ask the host for the LOID of its ImplementationC acheO bject Parameters HidType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host to check Return Values The LOID of the host object s implementation cache page 184 Reference J une 19 2001 Legion 1 7 Reference Manual Error Return NULL User Responsibility The useris responsible for free ing the memory returned by this function char ChangeObjectOwner LegionldType HidType char HostName LegionldType OOldType char OrigOwnerNm LegionldType NOldType char NewOwnerNm Change the owner of a certain object that the host is running Parameters HidType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host to check the vault with OOIdType A flag indicating whether OrigOwnerNm is a context path name or a LOID OrigOwnerNm The name of the original owner of the object NOIdType A flag indicating whether NewOwnerNm is a context path name or a LOID NewOwnerNm The name of the new owner of the object Return Values The LOID of the object s owner Error Return NULL User Responsibility The useris responsible for free ing the memory returned by this function
107. e which executed the original object debug Catch and print Legion exceptions help P rint command syntax and exit Reference page 77 J une 19 2001 Legion 1 7 Reference Manual legion stateless add workers lt class name worker namel gt worker name2 gt worker nameN gt debug help Creates additional MPL stateless object workers By default when a stateless class is created or registered in context space it instantiates a single worker That worker is used by all other objects wishing to call a remote method invocation on that class Adding more workers allows message calls to be handled more efficiently The lt class name parameter should be the stateless class object s contextname The worker name parameters should be the desired context name of the new worker objects Note that you can use full or relative path names The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_stateless_configure lt stateless class context path n number of replicas gt Ch host context path gt w max number work requests gt Fl1UsH debug help page 78 This command configures stateless Legion classes so that requests sentto a Stateless class are first routed to a proxy object which selects a worker to service the requests You can use flags to control the number of replica workers their placement and the number
108. eRecord_GetActivationld CUVaL_InstanceRecora char UVaL InstanceRecord GetHost CUVaL nstanceHecord char UVaL InstanceRecord GetVault CUVaL InstanceRecora int UVaL InstanceRecord GetTransferringOpr CUVaL_InstanceRecora char UVaL_InstanceRecord_GetTransferringToVault CUVaL_InstanceRecora int UVaL_InstanceRecord_GetTesting CUVaL_ nstanceRecora unsigned long UVaL InstanceRecord GetStartTestTime CUVaL_InstanceRecora unsigned long UVaL_InstanceRecord_GetXferTime CUVaL_InstanceRecora unsigned int UVaL InstanceRecord GetHostTries CUVaL InstanceRecord char LegionCollectionData GetLOID CLegionCollectionData long LegionCollectionData GetLastUpdateTime CLegionCollectionData These resource descriptions are in the formof a pe null terminated list of UVaL_ObjAttributes fe in string form char LegionCollectionData GetResourceDesc CLegionCollectionData All of the complicated C types that are indirectly represented here as typedefs to ints have internal members which are useful to access For that purpose a number of accessor functions are provided All function names are of the form lt c TypeName gt _Get lt C Field Reference page 179 J une 19 2001 Legion 1 7 Reference Manual Parameters All accessor functions take one parameter the variable of from which the user wishes to access a member Return Values All accessor functions return one
109. ea common MPI COMM WORLD Thefile mustlistone binary and any arguments perline Each line can also contain one or more 1egion mpi run flags but not f For example n 2 mpi programs mpitest n 3 mpi programs mpitest_c This would start a run of five instances two of mpitest and three of mpitest c If you use an option file Legion will ignore the n flag program name and any arguments given on the command line Any 1ags will be treated as defaults and applied to all processes executed by this command unless otherwise specified in the option file Fault tolerant mode There is a setofspecial legion mpi run flags for running in a fault tolerant mode ft Turn on fault tolerance s checkpoint server Specifies the checkpoint server to use R checkpoint server Recovery mode g ping interval Ping interval Default is 90 seconds r lt reconfiguration interval When failure is detected an object has not responded in the last x seconds restart the application from the last consistent checkpoint Default value is 360 seconds These flags are used in specific combinations You must use the ft in all cases and you mustuse either s or R The g and r flags are optional Please see section 10 1 10 on page 61 in the Basic User Manual for more information on running in fault tolerant mode Reference J une 19 2001 Legion 1 7 Reference Manual legion native mpi config host lt wrapper g
110. ean up the remote directory after the job finishes the remote host will wait six hours and then tar and move the entire directory to your context scratch space If you started 1egion run in blocking mode and you then kill the remote job 1egion run Will hang and must be killed by hand lt class path name binary local path name platform type help page 98 Registers a PVM task implementation This setup is not necessary for tasks that will only be started from the command line tasks that will not be spawned Given the class named in lt class path name gt the binary named in binary local path register and the architecture type currently Linux Solaris or SGI this command creates an implementation objectthat can then be used by the Legion PVM Library Once you ve registered an application you can run it You do notneed a special command to run a registered P VM program If necessary you can examine Legion context space with either legion ls pvm to list the Tids of running PVM tasks or legion 1s pvm tasks to listthe registered taskclasses You can also use Legion class utilities to examine the class state e g legion list instances page 17 For example to register a Linux binary named matmult in Legion enter legion pvm register pvm tasks matmult matmult linux The following option is supported help Print command syntax and exit Reference J une 19
111. ect By default this file object will only be passed to node 0 unless you include A stdout context path Map standard output to a Legion file object By default this file object will only be passed to node 0 unless you include A stderr context path Mapstandarderrorto a Legion file object B y default this file object will only be passed to node 0 unless you include A STDIN local file gt Map standard input to a local file By default this file will only be passed to node 0 unless you include A STDOUT local file gt Map standard output to a local file By default this file will only be passed to node 0 unless you include A STDERR local file Map standard error to a local file By default this file will only be passed to node 0 unless you include A A Pass the files in the std STD parameters to all nodes The default setting gives these files only to node 0 p context path S pecify a context path for the program s instance LOIDs If the context does not exist it will be created The default path is mpi instances program name If security is enabled the default is home user name mpi instances program name host context name Run the first process process zero on this node d Unix path name S pecify that all children change to the specified directory before they begin to run S Print statistics at exit D lt variable_name gt
112. ed object or environment all other entries in the file will be ignored This access control list is inherited by any newly created objects in the current login session it roughly corresponds to a Unix umask The following option is supported s Read from standard input debug Catch and print Legion exceptions help Print command syntax and exit legion_set_implicit_params c s lt object context name gt 1 object LOID gt filename debug help Set the implicit parameters of a specified AuthenticationO bject or if no object is named the current environment Any parameters that were previously set are cleared These are the parameters that the user inherits when he logs into Legion They are passed along as different Legion commands are executed and are similar to environment variables that user might set up in a Unix profile of cshrc file If no AuthenticationObject is specified the current Legion login session s implicitparameters are modified the changes will notpersist to the nextlogin session The command reads the implicit parameters from a file or the standard input A sample file can be found in LEGION src UserO bjects Security SamplelmplicitP arams The following option is supported s Read from standard input debug Catch and print Legion exceptions help Print command syntax and exit legion set message security c AuthenticationObject context path l Authent
113. egionBinding on the returned binding when done with it int Legion AcceptMethods Enables the receipt of messages in the Legion library This function must be called prior to any other function which might make outcalls to other objects or receive methods or return values from any other objects page 144 Reference J une 19 2001 Legion 1 7 Reference Manual Parameters None Return Values 1 on Success 0 on Failure User Responsibility None int Legion_DeleteSelf Indicates to the object s program s class that the program is finished and ready to go away After this function is called the user s code may run for some undetermined amount of time but will eventually be killed if it doesn t exit Parameters None Return Values 1 on Success 0 on Failure User Responsibility None void Legion Sleep int secs Causes the user s code to pause for approximately the number of seconds requested while still handling external Legion events such as method receives exception receives etc Parameters secs Number of seconds to sleep for Return Values None UserResponsibility None char ClassOf LegionldType IdType char ObjName Returns the LOID of the indicated objects class Parameters IdType Either CONTEXT PARAM or LOID PARAM indicating whattype of string name is given next ObjName Either a LOID or a context path to an object Return Values LOID of the indicated object s class
114. either a LegionBuffer or another LegionLOID LegionLOID Parameters None Not a very useful constructor so it prints a warning and assigns all data members to zero Useful constructors should at least say whatthe type is Accessors Methods for getting and setting the type and all field values by field number and field name exist Overloaded operators The and operators are overloaded appropriately An LOID is equal to another only if all fields are identical in size and value int is_empty Q Parameters None Returns 1 only if the LOID is of type UVaL_LegionLOID_ type_EMPTY zero int is_classQ Parameters None Returns 1 only if the LOID seems to refer to a class object i e the instance number field is empty int same_class_as Parameters UVaL_Reference lt LegionLOID gt other_loid Returns 1 if the class_id field matches that of other_loid int pack LegionBuffer amp lb Type and num fields are packed first in network order Next num fields shorts are packed in network order Next num fields values are packed int unpack Parameters LegionBuffer amp lb The type num fields and field size s are unpacked into host order The ield value s are unpacked without switching the byte order Reference page 137 J une 19 2001 Legion 1 7 Reference Manual int show Parameters None Prints the contents of the LOID to stderr for debugging purposes 7 5 LegionMessage LegionMessage Pa
115. ents of the LegionBuffer to stderr This is done however the associated LegionStorage sees fit Naming and binding LegionLOID LegionLOID is intended to be a base class for LOID s that enforce a particular structure on the fields of the LOID An LOID contains four private data members 1 an integer that holds the type of LOID 2 an integer that indicates how many fields the LOID contains 3 an array field size of integers that holds the sizes in bytes of the LOID fields and 4 an array ield value of pointers to the field data Currently the only derved class is called LegionGeneralPurposeLOID which simply exposes the protected members to the public interface Reference page 135 J une 19 2001 Legion 1 7 Reference Manual LegionLOIDY protected Parameters int ltype Sets the type to 1t ype sets all other fields to zero LegionLOID protected Parameters int Itype short nfields Sets the type to ltype Sets num_fields to nfields Allocates the field_size and field value arrays Sets all ield size s to 0 sets all ield value s to NULL LegionLOID protected Parameters int Itype short nfields short fld size Sets the type to 1type Sets num fields to nfields Allocates the ield size and field value arrays Sets all ield size s to the values contained in the fld size array Allocates the ield value entries to the right size and zeros them out This constructor assumes the fld
116. eptions help Print command syntax and exit legion_set_vault c instance context path 1 instance LOID gt c lt vault context path gt 1 lt vault LOID gt permanent debug page 20 help Migrates the state OP R ofthe objectnamed in instance LOID gt or instance context path to the vaultnamed in vault LOID gt or vault context path The following options are supported permanent Makes the migration permanent l e the object s acceptable vaultlist will be change to listonly the new vault No further migration can occur without user intervention via legion_instance_vault_list see page 49 debug Catch and print Legion exceptions help Print command syntax and exit Be careful with the permanent flag If none of the instance s acceptable hosts match the chosen vault i e there are no compatible host vault pairs the instance cannot be reactivated Alternatively the chosen vault may be compatible only with hosts for which the class has no implementation Please note that this command can fail for many reasons including e The instance does not exist e The user does not have permission to perform the migration e The target vault does not exist Thetargetvault will notgrantthe requestto create a new OPR for the object e The source vault is unavailable or will not grant the request to getthe current OPR Other machine or system failure e The specifie
117. es First MaxNum context path names of the object These paths are stored in a NULL terminated array of strings Error Return NULL User Responsibility The user is responsible for free ing each name returned in the list well as the list itself char ContextPWD Return the context path name of the current context Parameters None Return Values context path name of the current context Error Return NULL User Responsibility The user is responsible for free ing the context path name returned char legion_mkdir char PathName Creates a new context named by the given path Parameters PathName The new context s path name Return Values LOID of the new context that was created Error Return NULL User Responsibility The user is responsible for free ing the context LOID Reference page 151 J une 19 2001 Legion 1 7 Reference Manual int legion cd char PathName Change the current contextto the one named in the path NOTE that this only changes the current context for the running program notforthe shell or program that executed the program Parameters Pathname of the contextto change to Return Values 1 on Success 0 on Failure User Responsibility None 8 4 Legion object management The following section contains functions which are used to manage actual Legion Objects create activate destroy etc int ObjectActive LegionldType char Name Indicates whether the g
118. esponsibility The user is responsible for free ing each non NULL entry in the array as well as the array itself int ContextAdd char Name char Loid Add an entry to the current context This new entry will have the indicated name and will pointto the object with the given LOID This command assumes that the name is in the current context not a full path Parameters Name The name to add to the current context Loid The LOID ofthe objectto link into context space Return Values 1 on Success 0 on Failure User Responsibility None int ContextRemove char Name Remove an entry from the current context This entry must be in the current context It cannot be a path name but only a current context entry Parameters Name The name to remove from context space Return Values 1 on Success 0 on Failure User Responsibility None int ContextPathAdd char Name char Loia Add an entry to context space This new entry will have the indicated name and will pointto the object with the given LOID This command allows relative and absolute paths in context space to be added Parameters Name The name to path to add to context space LOID The LOID ofthe object to link into context space Return Values 1 on Success 0 on Failure Reference page 149 J une 19 2001 Legion 1 7 Reference Manual User Responsibility None int ContextPathRemove char Name Remove a path from context space Parame
119. ess 0 on Failure User Responsibility None page 172 Reference J une 19 2001 Legion 1 7 Reference Manual char RetrieveAttribute LegionldType IdType char ObjName char Attribute Retrieve an attribute from an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to which the attribute will be added Attribute The string representation of the attribute to retrieve from the object s attribute database Return Values The string representation of the attribute retrieved Error Return NULL User Responsibility The user is responsible for free ing the returned attribute char RetrieveAttributes LegionldType ldType char ObjName char Attributes Retrieve a setof attributes from an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the objectto which the attribute will be added Attributes A NULL terminated list of the string representations of the attributes to retrieve from the object s attribute database Return Values A NULL terminated list of the string representations of the attributes retrieved Error Return NULL User Responsibility The user is responsible for free ing each returned attribute in the list as well as for free ing the list itself
120. estricted Return Values NULL terminated array of LOIDs indicating the objects that were instantiated Each elementof the array is a char which is the LOID of one object created page 156 Reference June 19 2001 Error Return NULL Legion 1 7 Reference Manual User Responsibility User is responsible for free ing each LOID in the array as well as the array itself char Comp xScheduledCreateRestricted int NumObjects LegionldType CIDType char ClassName LegionldType HIDType char HostName LegionldType VIDType char VaultName LegionldType IIDType char ImplName LegionldType SIDType char SchedName Create a vector of new Legion objects by vector instantiating the given class The user also indicates any combination of restrictions which may include restrictions to hosts vaults or implementations In addition the user may specify a scheduler to use for the instantiation Parameters NumObjects CldType ClassName HidType HostName VidType VaultName IIdType ImplName SIdType SchedName Number of object to vector instantiate Flag indicating whether the ClassName parameter is a context path name or a LOID LOID or context path name of the class to instantiate Flag indicating whether the HostName parameter is a NULL terminated list of context path names or a NULL terminated list of LOIDs NULL terminated array of LOIDs or context path names of the H
121. ets of inputfiles or three jobs that can be run IN LOCAL SPACE IN CONTEXT SPACE mylocaldir fool ent mycontext barl gif mylocaldir foo2 ent mycontext bar2 gif mylocaldir foo3 ent mycontext bar3 gif These jobs can be identified by their pattern 1 2 and 3 Before going any further Legion checks for any previously created output files If it finds a file called mylocaldir output1 stuff itknows thatjob 1 has already been run The remaining jobs 2 and 3 have not Legion then copies the remaining four input files to the two hosts that will run the jobs mylocaldir foo2 ent Copied to gt HostA FooFoo mycontext bar2 gif HostA MyFoo mylocaldir foo3 ent HostB FooFoo mycontext bar3 gif HostB MyFoo The jobs are run and two output files each called Bar are created on HostA and on HostB HostA Bar s contents are copied to mylocaldir output2 stuff a file in the original host s local directory space signalling thatjob 2 is finished Host B Bar s contents are copiedto mylocaldir output3 stuff Signalling thatjob 3 is finished A more complex specification file might look like this IN FILEI usr localtmp dump pdb ent in NEXT2 home an4m pictures gif OUT THEN3 output out FILE4 dssp log CONSTANT Crypt etc passwd constant Salt File home admin user list Reference page 105 June 19 2001 page 106 Legion 1 7 Reference Manual The program must be written so as to read w
122. evant host and class hierarchy to find the cause of the problem legion translate arch legion vrun run legion vrun status legion vrun kill legion watch process page 118 Internal tool used to translate architecture names e g 1inux sgi alpha linux solaris etc to Legion s internal numbers for those architectures e g 1 6 4 2 etc and vice versa These three scripts are used for virtual hosts they sit on the physical host and are called by the virtual host object Please see section 14 0 in the System Administrator Manual This is a wrapper used to manage a long running process If the process itis managing dies with a non zero exit status or is killed the wrapper will automatically restart its child If the child exits with an exit status of zero the wrapper terminates If the wrapper receives a SIGINT ora SIGHUP itpasses the signal along to the child and exits Reference J une 19 2001 Legion 1 7 Reference Manual Manipulating hosts and vaults 5 0 Alternative ways to start and shut down 5 1 Starting extra hosts and vaults command line Please note that the procedure described below does not use rsh Classes as does the normal procedure described in Adding a new host and Adding a new vault starting on page 52 in the System Administrator Manual The rsh procedure is preferable if possible to the command line procedure since itis easier and faster The full procedure explained below can
123. ext path Or host LOID gt can interoperate Note also thatif you identify the hostby its contextname in the first parameter i e as foo you mustalso identify the vaults by their contextnames in the vaulti vault2 vaultn parameter Conversely if you use a LOID via 1 you must identify the vaults by their LOIDs Reference page 47 June 19 2001 Legion 1 7 Reference Manual Use the p flag to list the vaults that a host can operate on legion host vault list hosts HostName p COMPATIBLE VAULT LISTING EE 1 01 03 d49d1a40 000001 c0a69cbb845 The following optional parameters are supported 1 Use dotted hex LOIDs to specify host and vault a Add named vault to the host s acceptable vault list d Delete named vault from the host s acceptable vault list t Test whether or not a vault is on the host s acceptable vault list p Display the host s acceptable vault list debug Catch and print Legion exceptions help Print command syntax and exit You canuse the a a and t flags more than once when running the command but regardless of how you list them on the command line Legion will process themin a specific order when you run the command first adding any new vaults then deleting old vaults then testing any vaults and finally printing out the results legion_instance_host_list c lt instance context name gt 1 lt instance LOID gt a d t hosti host2
124. files between your local host the remote host and context Space You can also use an options file Use p to set a job s priority in the priority queue Priorities are used when the numberofsubmitted jobs is largerthan the numberofjobs that are allowed to execute simultaneously If so the job with the highest priority will be allowed to execute when a slot becomes available The command will propagate tty information to the J obQueue objectso that stdout and stderr output can to redirected to 1egion nq window JobQueue A J obQueue can be used to start monitor and clean up remote jobs The J obQueue object is owned by the Legion system administrator i e the admin user and takes care of preparing starting and monitoring the job s progress It assigns a ticketto each submitted job and a job record which hold job related information and puts the job in a priority queue The system administrator sets a maximum number of simultaneously running jobs with 1egion manage queue page 83 and the J obQueue tries to start jobs as slots become available Ifthe job starts successfully its record is moved the listof running jobs Ifitfails its record is moved to the listoffailed jobs The job will be retried after anotherjob has been started orhas failed orthe number of job slots is increased Waiting jobs can be given higher and lower levels of priority by the job owners and or the system administrator The J obQueue does not block and wait
125. following parameters f ile specification file path Local path name of specification file program class name The program s Legion class name created when the program was reg istered in Legion Options The following options are available with this command help P rint command syntax and exit debug Turn debugging mode on In this mode 1egion run multi prints copious output regarding which patterns must be run This flag also turns on the verbose mode v v erbose Provide a verbose output as the command is running z ero Consider input and output files of zero size to be valid If this option is used a zero sized input file can be used to start a job and a zero sized Reference page 107 June 19 2001 r estart e xec command x exceptions file path a rch architecture d ir dir D var value time lt timefile gt lt argl gt lt arg2 gt lt argn gt Legion 1 7 Reference Manual output file can be used to signal a completed job Restart incomplete jobs will attempt five times max Run some other command The defaultis 1egion run The exceptions file s Unix path Platform architecture for remote hosts Remote directory to which each job must change before execution Environment variable to be set for each job S pecify a file for recording the job history ofthe processes This file will listjobs by their name and gives the time
126. for a job to finish When a job terminates for whatever reason its job proxy object an object on the remote host which actually starts the job notifies the J obQueue object The JobQueue also periodically pings running jobs updates job Statistics kills jobs that have either overrun their maximum allocated running time and removes jobs records marked for deletion Reference page 93 June 19 2001 page 94 Legion 1 7 Reference Manual A Legion system can have multiple J obQueue objects responsible for different parts of the system s resources You can use legion manage queue to manage individual J obQueue objects Note thatjobs run with the J obQ ueue still mustbe registered with either the legion register program page 99 or legion reg ister runnable page 99 Parameter The following parameter is used with this command program class Specifies the program class of which an instance should be executed This program class should have been previously created with the legion register program page 99 Or legion register runnable page 99 command Options The following options are supported help Print this help message w Display standard I O from the remote program v Verbose mode a architecture Specify the preferred Legion platform type on which the remote program should run h host context path Specify the context path of the Legion host object on which the remote pro gram should run
127. formation and default values for selected parameters and exit v Operate in verbose mode All commands and responses will be echoed to stdout p port number Specify a listening port for incoming FTP connections a All machines other than the local host to connect to the daemon m max connections Specify the maximum number of simultaneous FTP connections t lt transfer block size Specify the block size in bytes for Legion file object invocations o max outstanding invocations gt Specify the maximum number of outstanding Legion remote method invocations If the a flag is also enabled only max outstanding page 80 Reference J une 19 2001 W e rt lt RMI timeout dt detail timeout legion link CC compiler Fortran FC compiler pvm mpi L library path gt l lt library gt v o lt output file gt bfs lt object file list debug help Legion 1 7 Reference Manual invocations Will simultaneously be queried for details This flag also restricts the number of simultaneous file transfer block requests sends S pecify thatobject details be retrieved during directory listings If the a flag has been enabled Unix style world access rights r w x will be displaced during directory listings The SITE CHMOD command will also be enabled allowing modification of individual object s world rights Encryptall Legion communications If y
128. h LOID represents one hostthat is compatible with the given vault Error Return NULL Reference page 187 J une 19 2001 Legion 1 7 Reference Manual User Responsibility The user is responsible for free ing each LOID as well as for free ing the list itself int TransferOPRsAndDestroySelf egionldType VidType char VaultName Ask the vault to transfer all of its OP Rs to another vault and then to die Parameters VidType A flag indicating whether VaultName is a context path name or a LOID VaultName The name ofthe vault to talk to Return Values 1 on Success 0 on Failure User Responsibility None char ChangeOPROwner LegionldType VidType char VaultName LegionldType OOldType char OrigOwnerNm LegionldType NOldType char NewOwnerNm Change the owner of a certain OPR thatthe vaultis managing Parameters VidType A flag indicating whether VaultName is a context path name or a LOID VaultName The name ofthe vault to talk with OOldType A flag indicating whether OrigOwnerNm is a context path name or a LOID OrigO wnerNm The name ofthe original owner of the OPR NOIdType A flag indicating whether NewO wnerNm is a context path name or a LOID NewO wnerNm The name of the new owner of the OPR Return Values The LOID of the OPR s owner Error Return NULL User Responsibility The useris responsible for free ing the memory returned by this function page 188 Reference J une 19
129. h name or a LOID ImpIName LOID or context path name of the Impl to which the activation is restricted Return Values 1 on Success 0 on Failure User Responsibility None int ScheduledActivateRestricted LegionldType OIDType char ObjectName LegionldType HIDType char HostName LegionldType VIDType char VaultName LegionldType IIDType char ImplName LegionldType SIDType char SchedName Activate an inert Legion object but subject to the restrictions indicated by the user Also use the indicated scheduler to schedule the activation Parameters OIDType Flag indicating whether the ObjectName parameter is a context path name or a LOID ObjectName LOID or context path name of the object to activate Reference page 159 J une 19 2001 Legion 1 7 Reference Manual HIdType Flag indicating whether the HostName parameter is a context path name or a LOID HostName LOID or context path name of the Host to which the activation is restricted VIDType Flag indicating whether the VaultName parameter is a context path name or a LOID VaultName LOID or context path name of the Vault to which the activation is restricted IIDType Flag indicating whether the ImplName parameter is a context path name or a LOID ImpIName LOID or context path name of the Impl to which the activation is restricted SIDType Flag indicating whether the SchedName parameter is a context path name or a LOID SchedName LOID or context p
130. he exported files re execute the command specifying the same local base directory path and target context path Y ou can also run 1egion rm r on the new context which will recursively delete the context and its contents to stop the command You can make changes to the shared local directory while the command is running butthose changes won t be reflected in context space unless you use the autorehash flag or run legion export dir rehash below The following parameters are required local directory path A local directory or directory tree that you wish to export to Legion context Space target context path A new context path which will hold copies of the exported directory tree The following options are supported v Verbose mode Prints information about which files and directories the command is currently exporting help Print command syntax and exit noserver Keep the program attached to a terminal so thatitcan be shutdown via C and its output can be monitored autorehash Periodically check the shared local directory so that any changes are reflected in context space page 30 Reference J une 19 2001 Legion 1 7 Reference Manual legion export dir quit target context path To be used in conjunction with 1egion export dir above Pauses legion export dir forthe specified context path The following parameter is required target context path A context path holding copies of an e
131. he specified vault Cv Select the backup vaults from the specified context path n Number of vaults to be selected legion set binding agent unset make default make default only l object context path c object LOID gt Setorunsetthe binding agentnamed in object context path Or object LOID gt as the user s current and or future login session binding agent The following options are supported unset Clear the current binding agent make default Set the specified binding agent to be the users binding agent for the current login session and any future login sessions make default only Set the specified binding agent to be the user s binding agent for the any future login sessions but do not set it as the current session s binding agent legion set host c instance context path 1 instance LOID gt c host context path 1 host LOID gt debug help Calls the set host class mandatory member function on the class of the instance named by in instance LOID gt Or instance context path gt Causing the instance to migrate to the hostnamed in host LOID gt Of host context path In the example below objectFoo s hostis changed from BootstrapHost to newHost Reference page 19 June 19 2001 Legion 1 7 Reference Manual legion set host c Foo c hosts newHost The following options are supported debug Catch and print Legion exc
132. help c class context name 1 class LOID gt Deactivates all instances of the class named in lt class context path Or class LOID Instances that are already deactivated will be unaffected The following options are supported stay down Forces instances to stay inactive They can only be reactivated by 1egion allow activation see page 26 debug Catch and print Legion exceptions help Print command syntax and exit legion_destroy_instances c lt class context name 1 class LOID gt debug help Destroys all instances ofthe class named in lt class context path Or class LOID gt Any active instances are deactivated This command will remove the LOIDs ofthe specified class instances in all contexts not justthe current context However it will not remove any context name associated with this object you must use the legion rm command to remove the object s name s or you will get binding errors You can use 1egion 1s A to check for multiple context names The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_direct_output c lt object context path 1 object LOID gt c lt tty context path gt 1 lt tty LOID gt debug help Causes the object named in object path or object LOID gt to direct its output standard out and standard error to the Legion tty objectnamed by tty con
133. her parameter is a LOID ora context path name Name Either the context path name or the LOID of the object to deactivate Return Values 1 on Success 0 on Failure User Responsibility None int GetObjectType LegionldType ldType char ObjName Returns an integer which indicates as specifically as possible what type of object the user is talking about Parameters IdType Flag indicating whether parameter is a LOID or a context path ObjName Eitherthe context path name or the LOID of the objectto be described Return Values Returns an integer indicating the type of the object from the list above UserResponsibility None define EGION OBJ CONTEX 1 These constants are used x define EEGION OBJ FILE 2 to indicate what type of x define EGION OBJ RUNNABLE 3 object one is talking define REGION OBJ CLASS 4 about These are the x define EGION OBJ HOST 5 values that can be x define EGION OBJ VAULT 6 by GetObjectType x define EGION OBJ TTY 7 define EGION OBJ IMPLEMENTATION 8 Reference page 163 J une 19 2001 Legion 1 7 Reference Manual define EGION OBJ IMPLEMENTATION CACHE 9 define EEGION OBJ LEGION CLASS 10 define EGION OBJ BINDING AGENT 11 define EGION OBJ MPI 12 define EGION OBJ PVM3 13 define EGION OBJ UNKNOWN 14 int isContext Legionld
134. hether CollectionName is a LOID or a context name CollectionName Either the LOID or the context path of the collection object in question J oinerlDType A flag indicating whether J oinerName is a LOID or a context path J oinerName Either a LOID ora context path for the object being added to the collection Attributes NULL terminated array of object attributes Return Values 0 on Failure 1 on Success User Responsibility None Reference page 199 J une 19 2001 Legion 1 7 Reference Manual int LeaveCollection LegionldType Collectionld Type char CollectionName LegionldType LeaverldType char LeaverName Indicate that an objectis leaving a Collection Parameters CollectionIDType A flag indicating whether CollectionName is a LOID or a context name CollectionName Either the LOID or the context path of the collection object in question LeaverlDType A flag indicating whetherLeaverName is a LOID or a context path LeaverName Either a LOID ora context path for the object leaving the collection Return Values 0 on Failure 1 on Success User Responsibility None int UpdateCollectionEntry LegionldType CollectionldType char CollectionName LegionldType ConstituentldType char ConstituentName char Attributes Update a collection entry s data Parameters CollectionIDType A flag to show if CollectionName is a LOID or a context name CollectionName Either the LOID or the contex
135. hich do not directly interact with Legion Parameters char ClassID The representation of the class which instantiated the given object These are not strings so much as byte arrays int ClassldLen Length of the byte array given for ClassID Return Values 1 on Success 0 on Failure User Responsibility None int Legion_init_command_line_class Initializes the legion library for a Legion object started on the command line as a main Legion program For most client tools this version of create will be the one used This function or one of the other init functions must be called in all Legion programs before any other Legion calls are made This does not preclude Reference page 143 J une 19 2001 Legion 1 7 Reference Manual calls to the CLegionLib which do not directly interact with Legion Parameters None Return Values 1 on Success 0 on Failure User Responsibility None char Legion_GetLegionClassLOID Obtains the string representation of the LOID of the LegionClass object Parameters None Return Values LOID of the LegionClass object Error Return NULL User Responsibility Useris responsiblefor free ingmemoryallocatedfortheLOID CLegionBinding Legion GetLegionClassBinding Obtains the current binding for the LegionClass object Parameters None Return Values LegionBinding for LegionClass object Error Return 0 User Responsibility User is responsible for calling DestroyL
136. ibility None int MessagelmplicitParm InsertString char ParmName char Str Insert a new String Implicit Parameter into the implicit message parameter database Parameters ParmName The name of the implicit parameter to which the action is being applied Str The new String to add to the database Return Values 0 on Failure 1 on Success User Responsibility None int MessagelmplicitParm Remove char ParmName Remove an implicit parameter from the implicit message parameters database Parameters ParmName The name of the implicit parameter to which the action is being applied Return Values 0 on Failure 1 on Success User Responsibility None char MessagelmplicitParm FindLOID char ParmName Find an implicit parameter in the implicit message parameters database this parm must be a LOID parameter Parameters ParmName The name of the implicit parameter to which the action is being applied Return Values The string representation of the LOID that was found Error Return NULL page 196 Reference J une 19 2001 Legion 1 7 Reference Manual User Responsibility The user is responsible for free ing the returned LOID when done int MessagelmplicitParm_FindInt char ParmName Find an implicit parameter in the implicit message parameters database this parm must be an int parameter Parameters ParmName The name of the implicit parameter to which the action is being applied Retur
137. icationObject LOID Off page 70 Protected Private help This command updates the message layer security setting of an AuthenticationObject or the current environment by changing the MessageSecurity implicit parameter There are three possible Reference June 19 2001 Legion 1 7 Reference Manual settings Off Protected and Private The setting determines the object s message encryption level The default setting is Protected The arguments take the same input format as legion add implicit params page 62 New parameters merge into the existing implicit parameter set i e new parameters override old ones of the same name You must include one of the following parameters Off No encryption or digesting of messages Protected Message digested for verification and credentials encrypted for authentication Private Message and credentials encrypted for authentication and verification The following option is supported help Print command syntax and exit legion show acl c lt object context path l object LOID gt lt function pattern gt showLoids Display an object s access control list ACL in human readable form The optional lt functionpattern gt argumentallows you to use Unix like wildcard arguments to control which functions are listed The output may list one or more users as Unknown This means that you do not have permission to see that user s s context name The foll
138. identity CLegionReservation CreateReservation CLegionHostReservation CLegionVaultReservation char InstancePlacementinfo Getinstance CInstancePlacementinfo char InstancePlacementinfo_GetHost C nstancePlacementinfo char InstancePlacementinfo_Getlmpl C nstancePlacementinfo char InstancePlacementinfo_GetVault C nstancePlacementinfo CLegionReservation InstancePlacementinfo_GetRSVN C nstancePlacementinfo int InstancePlacementinfo_GetArch C nstancePlacementinfo CInstancePlacementinfo CreatelnstancePlacementinfo char nstanceL OID LegionldType char HostName LegionldType char ImplName LegionldType char VaultName CLegionReservation int Arch char HostObjectStatus GetLoid CLegionHostObjectStatus char HostObjectStatus GetOwner CLegionHostObjectStatus int HostObjectStatus GetActivationID CLegionHostObjectStatus int HostObjectStatus GetStatus CLegionHostObjectStatus int HostObjectStatus GetErrorCode CLegionHostObjectStatus CLegionBinding HostObjectStatus GetBinding CLegionHostObjectStatus char UVaL_InstanceRecord_GetLoid CUVaL_InstanceRecora Reference June 19 2001 Legion 1 7 Reference Manual char UVaL InstanceRecord GetOwner CUVaL nstanceRecord int UVaL_InstanceRecord_GetStatus CUVaL_InstanceRecora char UVaL_InstanceRecord_GetCommandLineObj CUVaL_InstanceRecora unsigned long UVaL_InstanceRecord_GetLastTransitionTime CUVaL_InstanceRecora int UVaL_Instanc
139. igned aliases Legion will randomly return one of the context paths Your output will look something like this legion whereis Foo Host hosts BootstrapHost Vault vaults BootstrapVault Reference June 19 2001 legion whoami debug help Legion 1 7 Reference Manual This example looks up the location of objectFoo The outputshows that the objectis located on Boot strapHost and its persistent state is on BootstrapVault The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit You can use this command to find out which user id you are currently logged in with For example if you log in as user nemo your output will be legion whoami users nemo The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Reference page 61 J une 19 2001 2 8 Security legion add acl c object context path 1 object LOID gt s lt filename gt debug Legion 1 7 Reference Manual help Adds an access control list to the object named in lt object LOID gt or object context path or if no object is named the current environment This command resembles legion set acl but it merges in a new access control list For example ifthe currentaccess control set contains access control lists for methods A and B of class XYZ s instances adding new access control l
140. ing the list itself char GetCompatibileVaults LegionldType HldType char HostName Ask the host to return a list of vaults that are compatible with it Parameters HidType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host to check Return Values A NULL terminated list of LOIDs Each LOID represents one vault that is compatible with the given host Error Return NULL User Responsibility The user is responsible for free ing each LOID as well as for free ing the list itself int VaultOK LegionldType HidType char HostName LegionldType VidType char VaultName Ask the host if a certain vault is compatible with it or not Reference page 183 J une 19 2001 Legion 1 7 Reference Manual Parameters HIdType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host to check the vault with VidType A flag indicating whether VaultName is a context path name or a LOID VaultName The name of the vault to check for compatibility with Return Values 0 if the vaultis not OK 1 if the vault is OK Error Return 1 User Responsibility None int GetObjectStatus LegionldType HldType char HostName CLegionBinding Binding Ask the host for the status of one of its objects Parameters HidType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host to check th
141. int command syntax and exit Begins a replay or playback session for a recorded object This command is used in tandem with the 1egion recordtoolto debug a particular application The 1egion replay tool starts a debugging session for an object started in the application If used with the list option the command returns a listofthe sessions stored in the storage file the session number for each object that was started and the final states of the objects These session numbers can then be used to debug the objects one at a time by rerunning the command with the correct session number You must use one ofthe following sets of parameters to specify which session you wish to start Sessions are named in 1egion record see above If you used a Legion recorder object you ll need to provide the debug session name as well The following options are supported uf local storage file The local file that was used to record your session c recorder context path The Legion recorder object that was used to record your session must be accompanied by debug session name name debug session name The desired debug session name list Display the sessions in the storage file cmd lt debugger gt S pecify a debugging program e g gdb xdb etc to run on the storage file Default is gdb local Indicates that the debugging session should be replayed on your local machine The default will start a remote session on the machin
142. ion The following section contains functions which allow for manipulation of typedefs which are normally C classes void Show CLegionHostReservation CLegionHostReservation FILE void Show CLegionHostReservationRecord CLegionHostReservationRecord FILE void Show CLegionVaultReservation CLegionVaultReservation FILE void Show CLegionVaultReservationRecord CLegionVaultReservationRecord FILE void Show CLegionReservation CLegionReservation FILE void Show CLegionBinding CLegionBinding FILE void Show CLegionHostObjectStatus CLegionHostObjectStatus FILE void Show CLegionOPRAddress CLegionOPRAdaress FILE void Show CUVaL InstanceRecord CUVaL InstanceRecord FILE void Show CiInstancePlacementinfo CInstancePlacementinfo FILE void Show CLegionCollectionData CLegionCollectionData FILE Call the C show function on the given C class named by Show xxx Parameters All show functions take two parameters the type to show and the stream to show the output on Return Values NONE UserResponsibility NONE page 176 Reference J une 19 2001 Legion 1 7 Reference Manual void DestroyHostReservation CLegionHostReservation void DestroyHostReservationRecord CLegionHostReservationRecora void DestroyVaultReservation CLegionVaultReservation void DestroyVaultReservationRecord CLegionVaultReservationRecora void DestroyReservation CLegionReservation
143. ion The remote file will have the same name as the Legion file Note thatthis file will only be passed to node 0 unless you use a This flag can be used multiple times to indicate multiple input files You can also use wild cards to specify groups of files out output file Name of an output file that should be copied from the remote program s current working directory into your context space after the program terminates Note that this file will only be passed to node 0 unless you use the a flag The new file object will have the same name as the original output file object unless a is used in which case the name will be name mpi object 6 There is setof special flags for running in a fault tolerant mode listed on page 90 7 The output files will be copied out when the program calls MPI Finalize OTMPI Abort page 86 Reference June 19 2001 IN local input file OUT output file gt a Legion 1 7 Reference Manual id gt This flag can be used multiple times You can also use wild cards to specify groups of files Output files that are not found in the program s current working directory will be copied but will appear as empty files If the program crashes the files will be left in the program s current working directory Tells Legion to copy a local file to the remote program s current working directory before execution The remote file will have the same name as the local
144. ion always sends the return value of a method request back to the invoker If the invoker wishes to receive other result values that e g might correspond to in out parameters to the method invocation then those values must be explicitly asked for using add_result_dependency This call then creates a LegionContinuation corresponding to the requested parameter page 130 Reference J une 19 2001 Legion 1 7 Reference Manual UVaL_Reference lt LegionBuffer gt get value Parameters UVaL_Reference lt LegionInvocation gt inv int parameter_number Gets the specified return value for the given LegionInvocation out of the program graph This is essentially a call through the program graph to the underlying message database If the result is not available get value blocks until itis A LegionBuffer is returned int execute Parameters None Takes the program graph rooted atthe provided invocation and fire it off to be executed Does not block 7 2 LegionlnvocationStore int enable function Parameters intfunc num int priority Enables the supplied function so thatthe LIS will accept method requests for it Method requests for disabled functions are not accepted High values for priority mean high priority int any ready Parameters None Check to see if any method requests are ready int any ready for func Parameters intfunc num Check to see if any method requests for the given function are ready UVaL ReferencecLegion
145. ion begins The local file will have the same name as the context path name basename out context path name gt Copy the specified Legion file object out of the remote program s current working directory after the program terminates The local source file will have the same name as Outputfiles are copied out regardless ofthe cause of program termination so partial results will be available if the program crashes Output files not found in the 10 In all cases legion run blocks for ten seconds after you startthe command This is to be sure thatthere are no fatal errors that prevent the job from starting such as a dead remote host or conflicting parameters Reference page 101 June 19 2001 page 102 Legion 1 7 Reference Manual program s current working directory will be skipped IN 1ocal file name Similarto the in option butoperates on a file in the local execution environment of legion run ie the file named in local file name OUT local file name Similar to the out option but operates on a file in the local execution environment of legion run ie the file named in local file name stdin local file name Specify a local file from which the remote job gets its standard input stdout lt local file name gt Specify a local file to which the remote job writes its standard output stderr local file name gt Specify a local file to which the remote job writes its s
146. ion list attributes 10 legion list domains 25 legion list host accounts 40 legion list implementations 17 legion list instances 17 legion list invocations 10 legion list names 31 legion list objects 58 legion list oprs 50 legion list sub collections 50 legion In 32 legion login 68 legion logout 68 legion Is 32 legion make 73 legion make multi 74 legion make schedule 50 legion make setup script 40 legion manage job 82 legion manage queue 83 legion mkdir 33 legion modify parameters 69 legion mpi debug 83 legion mpi probe 84 legion mpi register 85 Reference page 205 J une 19 2001 Legion 1 7 Reference Manual legion mpi run 85 legion mplc 75 legion mplc reg impl 75 legion mv 34 legion native mpi config host 90 91 legion native mpi init 91 legion native mpi register 91 legion native mpi run 92 legion nq 93 legion object info 10 legion output state 75 legion passwd 69 legion ping 9 legion print config 40 legion print domain cookie 25 legion probe run 96 legion pvm register 98 legion pwd 34 legion query collection 51 legion record 76 legion refresh local cache 18 legion register program 99 legion register runnable 99 legion remove host account 41 legion remove sub collection 53 legion replay 77 legion rm 34 legion run 100 legion run multi 104 legion set acl 70 legion set backup vaults 7 18 legion set binding agent 19 legion set context 35 legion set default placement 53 legion set host 19 legion set implicit param
147. ionCollectionData 176 Show CLegionHostObjectStatus 176 Show CLegionHostReservation 176 Show CLegionHostReservationR ecord 176 Show CLegionOPRAddress 176 Show CLegionReservation 176 Show CLegionVaultReservation 176 Show CLegionVaultR eservationR ecord 176 Show CUVaL InstanceRecord 176 UVaL InstanceRecord GetActivationld 179 UVaL InstanceRecord GetCommandLineO bj 179 UVaL InstanceRecord GetHost 179 UVaL InstanceRecord GetHostTries 179 UVaL InstanceRecord GetLastTransitionTime 179 UVaL InstanceRecord GetLoid 178 UVaL InstanceRecord GetOwner 179 UVaL InstanceRecord GetStartTestTime 179 UVaL InstanceRecord GetStatus 179 UVaL InstanceRecord GetrTesting 179 UVaL InstanceRecord GetTransferringO pr 179 UVaL InstanceRecord GetTransferringToVault 179 UVaL InstanceRecord GetVault 179 page 208 Reference J une 19 2001 UVaL InstanceRecord GetXferTime VaultReservationRecord GetObjLoid VaultReservationRecord GetStatus CError h file class objects Activatelnstance AddImplementation Deactivatelnstance Deletelnstance ForcedDeactivatelnstance GetlnstanceList CLegionLib h file collections J oinCollection J oinCollection wData LeaveCollection QueryCollection UpdateCollectionE ntry context space ContextAdd ContextLookup ContextM ultiLookup ContextM ultiR everseLookup ContextP athAdd ContextP athLookup ContextP athMultiLookup ContextP athR emove ContextP W
148. ionInvocation add invocation Parameters UVaL Reference LegionInvocation Add an invocation to the program graph Returns the invocation if successful NULL if not ParameterStatus add constant parameter Parameters UVaL_Reference lt LegionInvocation gt target UVaL_Reference lt LegionParameter gt parameter int parameter_number Adds the given parameter to the specified invocation as the parameter_number th parameter The parameter is a LegionParameter which means that it contains an already computed value The other possible is that it is an invocation parameter This means that the parameter itself is a LegionInvocat ion thus representing a computation thathas yet to be performed ParameterStatus add_invocation_parameter Parameters UVaL_Reference lt LegionInvocation gt source UVaL_Reference lt LegionInvocation gt target int source_parameter_number int target_parameter_number Adds the given source parameter as a parameter to the given target parameter This call creates what is called a LegionContinuation and adds the continuation to the continuation list for the source parameter When an invocation requestis eventually executed the invokee must know where to send the results of the execution Each LegionContinuation identifies a destination LOID to which a result should be sent void add result dependency Parameters UVaL_Reference lt LegionInvocation gt source int parameter_number The current implementat
149. ionldType ldType char ObjName char OldAttributeSigs char NewAttributes Replace a list of attributes in an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the object to which the attribute will be added page 170 Reference J une 19 2001 Legion 1 7 Reference Manual OldAttributeSigs A NULL terminated list of the string representations of the old attribute signatures to replace in the database NewAttributes A NULL terminated list of the string representations of the new attributes to put into the database These are of the form attribute signature attribute value Return Values 1 on Success 0 on Failure User Responsibility None int RemovehAttribute LegionldType ldType char ObjName char Attribute Remove an attribute in an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the objectto which the attribute will be added Attribute The string representation of the attribute to remove from the objects attribute database Return Values 1 on Success 0 on Failure User Responsibility None int RemoveAttributeSig LegionldType IdType char ObjName char AttributeSig Remove an attribute in an object s attribute database Parameters IdType Flag indicating
150. is replicated and stored in multiple vaults when it is deactivated so that if its main vault crashes its state is still available However the replication policy synchronizes the object s state when the object deactivates if the main vault crashes while the objectis still active the backup vaults will not have the object s current State If the object needs to be reactivated it will use an out of date state Therefore this command should only be used for objects that can tolerate potentially old states This functionality is currently supported for the following classes ContextClass BasicFileClass AuthenticationO bjectClass and ImplementationO bjectClass You can either give a listof specific vaults ora context path from which a specified number of vaults will be selected For example to add Vault2 and Vault3 to object Foo s list of backup vaults you would enter legion set backup vaults home mycontext Foo a vaults Vault2 a vaults Vault3 Reference June 19 2001 Legion 1 7 Reference Manual To add any two vaults from the vaults context you would enter legion set backup vaults home mycontext Foo Cv vaults n2 Use legion object info page 10 to view an object s list of backup vaults The following options are supported nodeac tivate Do not deactivate the specified object when setting up its backup vaults a Add the specified vaultto the object s list of backup vaults d Delete t
151. is responsible for destroying the vault reservation record when done int CancelVaultReservation LegionldType VidType char VaultName CLegionVaultReservation VtRes Cancel a previously made vault reservation Parameters HIdType A flag indicating whether VaultName is a context path name or a LOID page 186 Reference J une 19 2001 Legion 1 7 Reference Manual VaultName The name of the vault that will cancel the reservation VtRes The vault reservation previously made Return Values 1 on Success 0 on Failure User Responsibility None int HostOK LegionldType VidType char VaultName LegionldType HldType char HostName Ask the vault whether or not a certain host is compatible with it Parameters VidType A flag indicating whether VaultName is a context path name or a LOID VaultName The name of the vault that will check the host HIdType A flag indicating whether HostName is a context path name or a LOID HostName The name of the host to check for compatibility Return Values 0 if the hostis not OK lifthe hostis OK Error Return 1 User Responsibility None char GetCompatibleHosts LegionlidType VidType char VaultName Ask the vault to return a list of hosts that are compatible with it Parameters VidType A flag indicating whether VaultName is a context path name or a LOID VaultName The name ofthe vault to check Return Values A NULL terminated list of LOIDs Eac
152. ists for class XY Z s methods B and C will not change A replace B and add C The following options are supported s Read from stdin debug Catch and print Legion exceptions help Print command syntax and exit legion_add_implicit_params 1 AuthenticationObject LOID gt c AuthenticationObject context path gt s lt filename gt debug help legion change acl c lt object context path l object LOID gt function pattern modifications page 62 Add an implicit parameter to the AuthenticationObject named in AuthenticationObject LOID Of AuthenticationObject context path Or if no AuthenticationObject is named the current environment The arguments take the same input format as legion set implicit params New parameters merge into the existing implicit parameter set i e new parameters override old ones ofthe same name There is no way to remove orunsetselected implicit parameters in the A AuthenticationObject please see legion modify parameters On page 69 for information on changing your current session s implicit parameters The following option is supported s Read from stdin debug Catch and print Legion exceptions help Print command syntax and exit Change an access control list ACL fora setoffunctions on a specified Legion object Please note that if you have never altered the specified objects ACL before the object s permissions are by default se
153. iven object is currently active or inert Parameters IdType Flag indicating whether parameter is a LOID or a context path name Name Either a context path name or a LOID Return Values 1 if the object is active 0 if the objectis inert Error Return 1 User Responsibility None char Ping LegionldType char Name Ping a given object to see if itis responsive Parameters IdType Flag indicating whether parameter is a LOID or a context path name Name Either a context path name or a LOID Return Values LOID of the object pinged page 152 Reference J une 19 2001 Legion 1 7 Reference Manual Error Return NULL User Responsibility User is responsible for free ing the LOID returned char Create int NumObjects LegionldType char ClassName Create a vector of new Legion objects by vector instantiating the given class Parameters NumObjects Number of object to vector instantiate IdType Flag indicating whether the ClassName parameter is a context path name ora LOID ClassName LOID or context path name of the class to instantiate Return Values NULL terminated array of LOIDs indicating the objects that were instantiated Each element of the array is a char which is the LOID of one object created Error Return NULL User Responsibility User is responsible for free ing each LOID in the array as well as the array itself char ScheduledCreate int NumObjects LegionldType CIDT
154. l not update its state This command is implicitly called upon object deactivation This functionality is currently supported for ContextClass BasicFile Class AuthenticationObjectClass and ImplementationObjectClass objects The following option is supported nodeac tivate Do not deactivate the specified object when setting up its backup vaults Reference page 21 J une 19 2001 Legion 1 7 Reference Manual 2 3 Calls on LegionClass legion add class mapping metaclass LOID class LOID debug help This command notifies LegionClass that the meta class named by metaclass LOID gt is the class of the class named by lt class LOID LegionClass updates its class map accordingly The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_combine_domains v list of domain cookie files debug help J oins a setof Legion domains systems to create a single larger multi domain Legion system Before you run this command you mustobtain a copy ofthe Legion domain cookie files from all ofthe involved domains see legion generate domain cookie page 24 and legion print domain cookie page 25 including the current Legion domain If you are joining domain A to domain B and domain B has already been joined to domain C you will need cookie files from domains A B and C This provides transitivity in the system join All three domains will
155. l objects listed in this context the objects types and any context aliases associated with each listed object legion ls laA hosts context hosts context class hosts vaults home BootstrapHost object hosts BootstrapHost hosts host DNS name host DNS name object hosts BootstrapHost hosts host DNS name Reference June 19 2001 legion mkdir context path debug help Legion 1 7 Reference Manual According to this there are four names listed in hosts two referring to contexts and two to objects We can see from the alternative context names though thatBoot st rapHost and my host DNS name refer to the same object Youcannow use wildcards inthe context path parameter Please note that you must escape the character l e to search for context objects containing foo in their names you would enter legion ls foo You cannot use wildcards with the R flag Optional parameters do the following 1 List object type and information if available Objects of unknown type will be listed as object and faulty objects will be listed as not available a List hidden objects in the context i e those objects whose names begin with a character Examples would be the current and parent contexts L Listthe LOID associated with each entry R Print a recursive list of the current context You cannot use this flag with wildcards
156. l source2 gt lt pull sourcen gt d lt local target directory gt ot lt seconds gt it lt seconds gt This command retrieves accounting information logs from one or more specified pull sources and places them in the specified target directory in your local file space A pull source can be an individual host a list of hosts a class of hosts or a Unix file containing a list of Legion hosts Each hostis queried for its log of process job accounting information The host object s s current status is also retrieved and placed in the target directory as a log file If all the requested accounting information is successfully gathered the queried hosts are instructed to trim their logs You must include the following parameters lt pull sourcel gt pull source2 pull sourcen One or more hosts thatshould be queried foraccount information A pull source can be one ofthe following c host context path l host LOID gt Reference page 57 June 19 2001 Legion 1 7 Reference Manual Class host class context name gt ClassLoid host class LOID gt Context context containing a group of hosts File local Unix file gt If you use the File flag the specified file must contain a list of Legion host context paths or LOIDs d lt target directory A local directory that will contain the accounting logs The following options are supported v Run command in verbose mode This
157. licitP arm ReplaceLOID 194 MethodlmplicitP arm ReplaceString 195 Legion Library interface 143 ClassOf 145 GetMyLOID 146 Legion AcceptM ethods 144 Legion DeleteS elf 145 Legion GetLegionClassBinding 144 Legion GetLegionClassLOID 144 Legion init 143 Legion init command line class 143 Legion init with class 143 Legion Sleep 145 objects Activate 158 ActivateR estricted 159 ComplxActivateR estricted 160 ComplxC reateR estricted 156 ComplxS cheduledA ctivateR estricted 161 ComplxS cheduledC reateR estricted 157 Create 153 CreateR estricted 154 DeactivateO bject 162 DeleteO bject 162 DestroyObject 162 ForcedDeactivateO bject 163 GetO bjectT ype 163 isBindingAgent 167 isClass 165 isContext 164 isF ile 164 isHost 165 islImplementation 166 isimplementationC ache 166 isLegionClass 167 isMPI 167 isP VM3 168 isRunnable 164 isTTY 166 isVault 165 ObjectActive 152 page 210 Reference June 19 2001 Ping ScheduledActivate ScheduledActivateR estricted ScheduledCreate ScheduledCreateR estricted valid architectures vault objects CancelVaultR eservation ChangeOPROwner CheckVaultR eservation GetCompatibleHosts HostOK MakeReservationF romV ault TransferOP RsAndDestroyS elf H host object adding new command line procedure adding new rsh procedure restart extras command line shutting down extras command line hosts bootst
158. list of preferred vaults gt d recorder context path debug session name debug help Creates an instance ofthe class named in lt class LOID gt Or class context path No start up parameters will be supplied forthe class or new object The following options are supported h S pecify a host for the new object v S pecify a vault for the new object H S pecify the preferred host class s context path V S pecify the context path of the preferred vault Ch S pecify a contextwhich contains a listof the preferred hosts Cv S pecify a contextwhich contains a listofthe preferred vaults d Automatically starta legion_recordsession for the newly created object This allows you to debug server objects The objects relevant activity will be recorded by a previously started Legion recorder object named in recorder context path debug Catch and print Legion exceptions help Printcommand syntax and exit If the hn flag isn t used the hostis selected by the class Similarly the class will choose a vaultifthe v flag isn tused Normally this means thata random hostis selected butsome classes may act differently If the ch or cv flag is used the class will randomly choose a host or vault from the hosts or vaults listed in the specified context In both cases the system will notreturn the LOID ofthe randomly chosen host Theiegion host vault listandlegion vault host list page 47 and page 55 c
159. llection 45 legion_allow_activation 26 legion_bfs 73 legion_cat 26 legion_cd 26 legion_change_acl 62 legion_change_owner 63 legion_change_permissions 64 legion class host list 45 legion class vault list 7 46 legion classof 57 legion combine domains 22 legion config scheduler 47 legion configure profile 7 legion context add 27 legion context create 27 legion copy class 14 legion cp 27 legion create class 38 legion create implementation 23 legion create object 15 legion create object r 15 legion create stat tree 57 legion create user 65 legion create user object 66 legion deactivate instances 29 legion deactivate object 16 legion destroy host 39 legion destroy instances 29 page 204 Reference J une 19 2001 Legion 1 7 Reference Manual legion destroy object 17 legion destroy vault 39 legion direct output 29 legion export dir 30 legion export dir quit 31 legion export dir rehash 31 legion exports interface 8 legion ft initialize 80 legion FTPd 9 legion generate domain cookie 24 legion get accounting data 57 legion get acl 67 legion get host 31 legion get implicit params 67 legion get interface 9 legion get vault 31 legion host stats 58 legion host vault list 47 legion init Apps 67 legion init arch 24 legion init Extra 67 legion init HPC 67 legion init security 67 legion initialize 39 legion instance host list 48 legion instance vault list 49 legion join collection 49 legion leave collection 50 legion link 80 81 leg
160. logous to looking in a Unix profile or cshrc for which environment variables getsetatlogin and the latter is analogous to Unix printenv The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_init_Apps Initializes the Applications package which extends the basic Legion package Please see page 9 in the System Administrator M anual for more information on the Legion packages legion_init_Extra Initializes the Extra package which adds functionality to the core Legion system P lease see page 9 in the System Administrator Manual for more information on the Legion packages legion_init_HPC Initializes the High Performance Computing package which lets you run programs in Legion P lease see page 9 in the System Administrator Manual for more information on the Legion packages legion_init_security Creates the initial user called by default users admin in a new Legion system This command should be run immediately after legion initialize when you are starting your system The script creates a new contextcalled users a new userobjectcalled admin The contextname admin is placed in the new users context Y ou will be asked for a password Reference page 67 June 19 2001 legion login lt user id path debug help legion logout debug page 68 help Legion 1 7 Reference Manual After running 1egion init security
161. lorified interface to a long integer The Library also contains a class LegionComputationTagGenerator that creates random computation tags See the source code or on line documentation fora description of that class Constructors The default constructor creates a LegionComputationTag with an uninitialized initial value A constructor that takes a LegionBuffer as an argument unpacks the contents of the computation tag from that buffer Accessor functions LegionComputationTag exports public member functions to allow the value of the tag to be set and retrieved as a long integer show Parameters None Prints the contents of the LegionComputationTag to the stderr stream int pack int unpack Parameters LegionBuffer amp lb LegionComputationTag is packable 7 5 4 Other fields A LegionMessage also contains a LegionContinuationList and a LegionEnvironment LegionContinuationList iS simply a UVaL PackableSet of LegionContinuations and a LegionEnvironment iS a UVaL PackableSet of LegionEnvi ronmentItems Please refer to the on line documentation and source code for the interface to these classes page 140 Reference J une 19 2001 Legion Grid library 8 0 Grid library The CLegionLib h file contains the declarations for the C Library interface to the Legion system This library is specifically designed to allow ease of use in many languages including Fortran C C For additional fun
162. lt placement available See legion_set_default_placement 1 This policy value specifies that the class should always use its default S cheduler even if the Scheduler is not active This is recommended for user classes which usually require help from a Scheduler object when making placement decisions The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Reference J une 19 2001 Legion 1 7 Reference Manual legion set varch c host context path 1 host LOID gt arch debug help Seta virtual hostobject s architecture A virtual hostobjectlives on host A the physical host butactually represents host B the virtual host If the legion set varch command is notrun Legion will assume that the virtual host object s architecture is the same as its physical host The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion set vrun c host context path 1 host LOID gt path debug help This command configures a virtual host object A virtual host object lives on hostA the physical host but actually represents host B the virtual host Running this command indicates where the physical host can find scripts for starting and managing jobs on the virtual host The path parameter is the local path for those scripts To configure a T3E virtual hostobject you could run
163. lt user id c AuthenticationClass path S pecify the AuthenticationClass which you wish to instantiate Default is class AuthenticationClass debug Catch and print Legion exceptions help Print command syntax and exit Reference page 65 June 19 2001 legion create user object I page 66 c debug lt c help lass context name gt h host for new object f implicit parameter file gt Legion 1 7 Reference Manual l class LOID gt v vault for new object gt z password user name Creates a new objectto representa new Legion user id The new object can be an instance of the AuthenticationO bjectClass or another class that implements AuthenticationO bjects The following options are supported h host for new object Specify where the new object should be created v vault for new object Specify where the new object s persistent state should be stored f implicit parameters filename Z password debug help Reference This option names a file containing implicit parameters to be stored in the newly created AuthenticationObject handed outon legion_login The filename can be in which case the command reads the parameters from the standard input Note that these are not the implicit parameters that control the behavior of the new AuthenticationO bject Upon login the user s environment will be set to
164. n Values The integer parameter that was retrieved from the database Error Return Need to check LegionErrno for this one User Responsibility None char MessagelmplicitParm FindString char ParmName Retrieve a string parameter from the implicit message parameter database Parameters ParmName The name of the implicit parameter to which the action is being applied Return Values The string parameter retrieved from the implicit message database Error Return NULL User Responsibility The user is responsible for free ing the memory returned from this function call int MessagelmplicitParm ReplaceLOID char ParmName char Loid Replace an implicit message parameter in the database with another LOID parameter Parameters ParmName The name of the implicit parameter to which the action is being applied Reference page 197 J une 19 2001 Legion 1 7 Reference Manual Loid The Loid parameter to replace ParmName With Return Values 0 on Failure 1 on Success User Responsibility None int MessagelmplicitParm Replacelnt char ParmName int Value Replace an implicit message parameter in the database with another int parameter Parameters ParmName The name of the implicit parameter to which the action is being applied Value The value of the integer parameter to replace ParmName With Return Values 0 on Failure 1 on Success User Responsibility None int Messagelmplici
165. n combine domains page 22 A cookie file contains binding information forthe LegionClass in the current domain security credentials for joining to the current domain and information aboutthe contextspace ofthe currentdomain for creating interdomain context space links The default cookie file name is LegionDomainCookie domain id In a secure environment you mustbe logged inas users adminforthe current domain This ensures that the required credentials can be generated and saved in the cookie file The following optional parameters are supported debug Catch and print Legion exceptions help Print command syntax and exit Creates and registers implementation objects for commonly used classes in the current architecture This command is run on a new host to create its implementation objects in the proper place Implementation objects for specific binary executables can be created with the 1egion create implementation Utility page 23 The sample below run on a linux machine creates a set of implementation objects for a linux host legion init arch Initializing Legion implementations for linux Creating an implementation ContextObject for ContextClass Continue y yes Y yes to all n no N no to all v verbose V verbose all Y Creating an implementation MetaClassObject for LegionClass Creating an implementation ClassObject for VanillaMetaClass 4 TheT90 and T3E architectures must be used with virtual hosts
166. n is for class objects only v Run the command in verbose mode You will see a list of the ACLs that have changed debug Catch and print Legion exceptions help Print command syntax and exit z lt password gt h new home context gt c lt AuthenticationClass path gt user id path debug help This command is actually a simple wrapper around the legion create user object command The full command give more control to the creation of AuthenticationObjects The user id is the context name of an AuthenticationO bject the legion create object utility creates the objectand assigns itthe contextname givenin user idpath Please note thatthis argument is a full path relative or absolute Note also thatthe user id s context has nothing to do with thatuser s privileges in thatcontext Once a user is created the 1egion login command is used to log in The command will promptfor a password forthe new user unless you use the z option and will return the new object s LOID The following options are supported a admin path S pecify the admin object s context path Defaultis users admin z password S pecify the new user id s password The default setting will prompt for the password after the command has been run This option is notrecommended for casual use since the password will be visible on the command line h lt new home context Specify the new user s home context Defaultis home
167. n languages libraries core objects and implementing new Legion objects There are also man pages for all Legion commands included with the system files and several on line tutorials on the Legion web site http legion virginia edu 1 2 Style conventions The manuals at times refer to path names in Unix directory space and in Legion context space To avoid confusion the following style conventions are used throughout Legion documentation Unix DOS and local path names appear in a serif typeface Functions method names parameters flags command line utilities such as rm cp and 1egion 1s and context path names appear in fixed typeface Reference page 5 J une 19 2001 Legion 1 7 Reference Manual Legion commands Legion s command line tools support path like naming of objects within context space There are man pages for all of the commands listed here as well as resources on the Legion web site lt http legion virginia edu gt Man page usage is man command name Please see your system administrator if you are unsure about using man pages on your system There are other sources of information about Legion context space and commands the Legion web site has on line tutorials and a quick guide to all commands see http legion virginia edu documentation html You can also type command name help to see most commands full usage The following syntax is used to indicate optional and re
168. n the physical architecture of the selected host if this option is used e g a script S pecify a requested amount of time in minutes This option is only meaningful if the host selected to run the remote program enforces time limits for jobs Otherwise this option is not required Ifthe remote program is a native parallel job e g a program written to use the local vendor MPI implementation this option selects the number of nodes that should be allocated for the job This option is not meaningful if the host selected to run the remote program is a uniprocessor or does not support multi node allocations S pecify the maximum amountoftime in minutes that the queuing system will wait for the program to complete before attempting to restart it Default is 0 no restarts S pecify job priority for the queuing sys tem Value range from 0 to 9 0 being the highest priority The default is 5 Users can assign values from 5 to 9 Only system administrators can assign values 0 to 4 afterjob submission with the legion manage job page 82 command S pecify a J obQueue object Default is etc JobQueue Deactivate IN files and temporary contexts to save process slots Provide arbitrary command line argu ments for the program page 95 June 19 2001 legion probe run help debug 1 probe LOID gt page 96 Legion 1 7 Reference Manual v erbose in context path gt out context path
169. ne so the owner s Legion credentials cannotbe mapped to a Unix uid Therefore all objects in a Legion NFS mounted file system appear to be owned by the user accessing the objects Unix permissions bits are set according to that user s ability to access the object Group permissions mirror other permissions Example To NFS mounta Legion system you need to startthe two Legion NFS daemons 1mountd and 1n sd then run mount Both 1mountd and 1nfsd need static ports which are passed to mount We suggest that you use the P option to manually selecta port These steps might look something like this Reference June 19 2001 Legion 1 7 Reference Manual rpc lmountd f local path exports P 2001 rpc 1nfsd f local path exports P 2000 mount t nfs o port 2000 mountport 2001 MyHost legion legion dir The first command starts 1mountd and the second 1n sd The third mounts Legion in local file space Note that the first two commands provide a path for the exports file and a port number If you do not manually selecta port one will be chosen but you ll need to know the port number and pass itto mount Note that 1mounta interprets the root of Legion context space as legion In the mount command therefore you must pass it legion as the root ofthe directory to be mounted In the example above legion dir directory is the local path pointing to the mounted directory but you can use any existing path The follo
170. ng float double size t put ZZZ Parameters ZZZ source int how many Assumes that source points to an array of how many instances of type zzz Copies this data into the buffer after first performing the appropriate data conversion operation if necessary and appropriate for the type of LegionPacker that is instantiated page 134 Reference J une 19 2001 Legion 1 7 Reference Manual 7 4 4 1 4 5 7 4 6 74 7 7 4 8 size t get ZZZ Parameters ZZZ source int how_many Assumes that source points to enough space for an array of how many instances of type zzz Copies the next data from the LegionBuffer into this space after first performing the appropriate data conversion operation if necessary and appropriate for the type of LegionPacker thatis instantiated Operations on the associated LegionEncryptor S ince no encryption algorithms have been implemented the current encryption operations encrypt and decode are merely placeholders until the right set of encryption operations are defined Operations on the associated LegionCompressor Since no compression algorithms have been implemented the current compression operations compress and decompress are merely placeholders until the right set of compression operations are defined LegionP ackable int pack Parameters int unpack LegionBuffer amp lb LegionBuffers are themselves packable Other functions show Parameters None Prints the cont
171. nk the produced executable to the Legion PVM compatibility library mpi Link the produced executable to the Legion MPI compatibility library L library path Include the lt library path in the set of directories searched for libraries There is no space between the L and the library path l library Link against the specified library There is no space between the I and the library name v Provide a verbose output as the command is running o output path Specify the local path of the resulting program The default is a out bfs Link the produced executable to the Legion Basic Fortran Support BFS library debug Catch and print Legion exceptions help Print command syntax and exit help k cp lt priority gt fr nc q context name gt ticket number gt page 82 This tool manages a job started with the legion_nq page 93 command line tool You must provide the job s ticket number If the job has finished or failed 1egion manage joo will by default copy back output files clean up temporary files and mark the job s record for deletion Use nc to override this Use r to force the job to restart Only the job s owner and the system administrator can perform these operations The following parameter is used with this command lt ticket number gt The job ticket number assigned when you ran legion_nq page 93 The following options are supported help Print this help mes
172. nstructions DEFGH h hosts special host name 123 v IN tmp myJob ExtraStuff The first line tells Legion that you wish to run job DEFGH on a specific host The second line says thatjob 123 requires an additional inputfile and that you wish to run the job in a verbose form These instructions combine with any other specifications that were provided on the command line and or in the specification file Reference J une 19 2001 Legion 1 7 Reference Manual Limitations caveats warnings 1 Be sure that you use legitimate syntax in the exceptions file Do not specify flags that do not exist for that particular command e g there are no CONSTANT constant flags in legion run 2 f you specify a host in the exceptions file and an architecture on the command line with the a flag be sure that they match If you specify conflicting architectures Legion will be unable to process that particular job but it will run any other jobs Parameters You must specify atleast one of the following two parameters n number of processors Specify the number of processes running atone time s chedule schedule file S pecify a setofhostcontextpaths and how many processes are to be run on each host e g hosts Foo 3 to run up to three jobs on host object Foo The format of the schedule file is as below One host per line hosts firsthost 2 hosts secondhost 1 hosts thirdhost 7 Y ou must include both of the
173. nt command syntax and exit legion_copy_class v Rt c template context 1 template LOID gt new class path a lt attribute gt mc c metaclass context 1 metaclass LOID gt Make a copy ofa class object Y ou mustuse an existing class objectas the template The command creates another class object that has the same metaclass and implementations as the template The following parameters are required c template class path 1 template class LOID gt The original existing class object newclass path The new class object s context path The following options are supported v Run in verbose mode h Print command syntax and exit a lt attribute gt Specify an attribute that should be copied from the template to the new class object You can use this parameter multiple times to specify more than one attribute mc c metaclass path 1 metaclass LOID gt S pecify the new class object s metaclass default is the template s metaclass page 14 Reference J une 19 2001 Legion 1 7 Reference Manual legion create object c class context name gt 1 class LOID gt new object context path h host name on which to place new object gt v vault on which to place new object gt H context path of preferred host class gt V context path of preferred vault class gt Ch context containing list of preferred hosts gt Cv context containing
174. omiscuous Run in promiscuous mode so thatthe server will serve any host on the network This violates infsa s security premises so itis deprecated t no spoof trace By default 1n sd logs every access by unauthorized clients This option turns off logging of such spoof attempts for all hosts listed explicitly in the exports file v version Printthe currentversion numberofthe program The following signals are supported SIGHUP Reread the exports file and flush the file handle cache SIGIOT When compiled with the DCALL_PROFILING option this signal will cause 1n sd to dump the average execution times per NFS operation into ftmp nfsd profile SIGTERM Kills the daemon This is the preferred method since it allows proper termination of the object SIGUSR1 If 1nfsdis invoked with debugging options this signal toggles generation of debugging information Known bugs Currently chown is unsupported since the mapping between a Unix target UID and the corresponding Legion principal may not be available Legion contexts do not share the append only implementations of Unix directories On some platforms such as x86 Linux this discrepancy manifests itself as an error when you attempting to remove large directories that require multiple invocations of readdir For example if you run xm xr ona large contextsome subcontextentries may be left intact Y ou will see an error message indicating that the parent context
175. ommands willallow users to limitthe placement ofa given class s instances i e any instances ofclass Foo canonly be placed on hosts X Y and Z legion create object r c class context l class LOID new object context host name host architecture lt SLEGION gt S LEGION OPR SLEGION OPA binary path lt user id gt debug help Create a new object on a specified host with the rsh remote shell mechanism The object will be managed with rsh if the class it is 2 If preferred ssh can be used in place of rsh Reference page 15 June 19 2001 Legion 1 7 Reference Manual invoked on is an rshStartClass If this utility is invoked on a normal class normal objectcreate mechanism will be used and the object will not be managed by rsh This command is generally used only by the legion create class and legion create vault scripts not by users The additional arguments specify information for the rsh environment The following parameters are required c class context Or 1 class LOID The new objects class instance context path The new object s context path host name Specifies the hostupon which the new objectshould be placed Note thatthis should be a DNS name host architecture Specifies the host s architecture lt SLEGION gt Specifies the Legion environment variable on the rsh host SLEGION OPR Specifies LEGION OPR for host SLEGION OPA
176. on CreateR eservation 78 79 21 35 35 36 36 36 12 58 12 59 55 60 60 60 61 132 27 122 168 168 175 171 172 171 172 169 170 169 170 175 173 173 174 174 178 178 178 178 Reference Legion 1 7 Reference Manual page 207 J une 19 2001 Legion 1 7 Reference Manual DestroyHostO bjectS tatus 177 DestroyHostR eservation 177 DestroyHostR eservationR ecord 177 DestroyInstanceP lacementinfo 177 DestroyLegionBinding 177 DestroyLegionCollectionData 177 DestroyLegionOPRAddress 177 DestroyR eservation 177 DestroyUVaL InstanceR ecord 177 DestroyVaultR eservation 177 DestroyVaultR eservationR ecord 177 HostObjectStatus GetActivationID 178 HostObjectStatus GetBinding 178 HostObjectStatus GetErrorCode 178 HostObjectStatus GetLoid 178 HostObjectStatus GetOwnert 178 HostObjectStatus GetStatus 178 HostReservationRecord GetO bjLoid 177 HostReservationRecord GetStatus 177 InstanceP lacementinfo G etArch 178 InstanceP lacementinfo GetHost 178 InstanceP lacementinfo G etlmpl 178 InstanceP lacementinfo_G etInstance 178 InstanceP lacementinfo GetRSVN 178 InstanceP lacementinfo G etVault 178 LegionCollectionData GetLastUpdateTime 179 LegionCollectionData GetLOID 179 LegionCollectionData GetR esourceDesc 179 LegionReservation GetHostReservation 178 LegionReservation GetVaultReservation 178 Show ClInstanceP lacementinfo 176 Show CLegionBinding 176 Show CLeg
177. on context space S pecify the number of nodes for the remote MPI run Specify the amount of time requested for the remote MPI run This option is only meaningful if the host selected to run the remote program enforces time limits for jobs Indicate whether the application makes Legion calls see section section 10 2 5 on page 68 in the Basic User manual P rint command syntax and exit Catch and print Legion exceptions Arguments to be passed to the remote MPI program June 19 2001 legion nq Legion 1 7 Reference Manual help w v a arch h host context path gt in context name gt out context name gt IN local file name OUT local file name f options file novrun t lt minutes gt n lt nodes gt r lt minutes gt p lt priority gt d program class lt argl gt lt arg2 gt lt argn gt The legion_ng command submits jobs to a Legion J obQueue object When a job is submitted the J obQueue stores all necessary information forhandling this job and returns a ticket which can be used for future references to the job This command can be used in place of legion_run page 100 to starta job on a remote Legion host You cannot use legion_probe_run page 96 to probe a 1egion nq job You can use 1egion manage job page 82 to manage the job after it has started You can use the in out and IN OUT options to copy input and output
178. ons are supported 1 List all of the implicit parameters in the user s current Legion session p Printa specific set of implicit parameters in the user s current Legion session d Delete a specific implicit parameter ora set from the user s current Legion session a Add a new implicit parameter to the user s current Legion session debug Catch and print Legion exceptions help Print command syntax and exit legion passwd user id context l user id LOID gt debug help Changes a user s password the command will prompt for the new password You must be logged in as either admin or the user in order to successfully run this command You must provide the full context path for the user id e g user user id The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Reference page 69 June 19 2001 legion set acl tI c s Legion 1 7 Reference Manual lt object context name gt 1 object LOID gt filename debug help Sets the access control list of the Legion object named in object context path Or object LOID The default will setthe access control set for the current environment The input file should be an implicit parameters file see LEGION src UserO bjects Security SamplelmplicitP arams for an example The implicit parameters file will be scanned only for access control information pertaining to the specifi
179. ontext name The context that contains the MPI instance LOIDs associated with the job The following options are supported help Print command syntax and exit debug Run in debug mode v erbose Run in verbose mode all Perform operation on all instances default is instance 0 list List all files in the remote program s working directory in context path name gt Context path of a Legion file object whose contents should be copied into the remote program s current working directory after execution begins The local file will have the same name as the context path name basename out context path name gt Context path of a Legion file object whose contents should be copied out of the remote program s current working directory after the program terminates The local source file will have the same name as the context path name base name This tool will not check to see if the job has finished so itmay copy out an incomplete file IN local filename Similar to the in butoperates on a file in the legion mpi probe local execution environment i e the file named in lt local path name OUT local filename Similarto the out option but operates ona filein 1egion mpi probe s local Reference June 19 2001 legion mpi register Legion 1 7 Reference Manual execution environment i e the file named in lt local path name stat remote file name Print the status of a
180. ontext path or a local path Use the recursive mode x to export objects to local file space Analogous to the Unix cp command For example to copy the file object Foo to home myContext Bar you would enter legion cp Foo home myContext Bar This copies the contents of Foo in the new file object Bar in the home myContext path You can now use wildcards in the source path parameter for context space orlocal file space Please note that you mustescape the character The example below copies all files that start with Foo from local directory space into the home myContext context legion cp localsrc Foo home myContext The new file objects are assigned the same names e g if roo finds Fool and Foo2 the duplicate file objects will be at home myContext Fool and home myContext Foo2 Reference page 27 June 19 2001 page 28 Legion 1 7 Reference Manual Note thatyou cannotuse wildcards in a destination path and you cannot copy multiple files to a single file object The following optional parameters are supported y localsrc localdest V vault context path m P Reference Verbose mode Prints information about which files and directories the command is currently working on Recursive mode If the lt source path gt is a directory all of its contents are copied recursively Only files and contexts directories are handled If other objects are encoun
181. ontext path gt debug help legion setup state 7i debug legion shutdown f eae local debug help This command is used on PCD host objects It removes one or more account mappings from the host object s list of available accounts The user id parameter is the user s Unix user id If no host is named in the nost object LOID host object context path parameter your current host object will be the default host The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit help Creates OPRs for the basic Legion system objects This script should be run when starting a Legion system for the first time The following optional parameters are supported i Runthe command in an interactive mode debug Catch and print Legion exceptions help Print command syntax and exit Shuts down a running Legion system preserving the state ofall objects for subsequent reactivation of the system Optional parameters allow users to shut down individual hosts and to specify an interactive shutdown Optional parameters do the following local Shut down only a local host or vault f Force the termination of a system This may leave processes running however and prevent a system restart i Putthe shutdown in an interactive mode which provides prompts for user actions debug Catch and print Legion exceptions help Print command
182. osts to which the instantiation is restricted Flag indicating whether the VaultName parameter is a NULL terminated list of context path names or a NULL terminated list of LOIDs NULL terminated array of LOIDs or context path names of the Vaults to which the instantiation is restricted Flag indicating whether the ImplName parameter is a NULL terminated list of context path names or a NULL terminated list of LOIDs NULL terminated array of LOIDs or context path names of the Impls to which the instantiation is restricted Flag indicating whether the SchedName parameter is a context path name or a LOID Context path name or LOID of the scheduler to use when instantiating the class Reference page 157 J une 19 2001 Legion 1 7 Reference Manual Return Values NULL terminated array of LOIDs indicating the objects that were instantiated Each elementofthe array is a char which is the LOID of one object created Error Return NULL User Responsibility User is responsible for free ing each LOID in the array as well as the array itself int Activate LegionldType IType char ObjectName Activate an inert Legion object Parameters IdType Flag indicating whether the ObjectName ObjectName LOID or context path name of the object to activate Return Values 1 on Success 0 on failure User Responsibility None int ScheduledActivate LegionldType OIDType char ObjectName LegionldType SIDType char SchedName Ac
183. ou setthis option and do not enable the a flag you will have the highest level of data security Specify the Legion remote method invocation RMI time out value in seconds Specify the time out value for looking up object details use in conjunction with the a flag This command links together a set of object files and libraries to produce an executable program and automatically binds the produced executables to the Legion libraries Itis similarto the Unix 1a command It can be used with object files and libraries created from C C or Fortran source code If any Fortran object files are linked the Fortran flag must be included If you specify a Fortran compiler with the Fc flag the Fortran flag is automatically implied The following options are available with this command CC compiler Selecta C compiler to perform linkage The default value is based on the default compiler used by the Legion system on your platform Fortran This flag must be included if any Fortran object files are linked FC compiler Selecta Fortran compiler This flag implies the Fortran flag but the two can be used together Currently supported compiler Reference page 81 J une 19 2001 legion manage job Legion 1 7 Reference Manual options are fort Compaq Fortran compiler Alpha Linux only g77 Gnu g77 pgf77 Portland Group pgf77 compiler Intel Linux pgf90 Portland Group pgf90 compiler Intel Linux pvm Li
184. ountd is invoked with debugging options this signal toggles generation of debugging information rpc lnfsd f exports file local path exports file exports file local path gt d debug lt facility gt P port port number gt F foreground h help 1 log transfers n allow non root p promiscuous t no spoof trace v version The Legion NFS process server daemon interposes an NFS clientand the Legion file system It is a user level process derived from Linux nfsd ltaccepts NFS RPC requests from a kernel client and translates them to invocations on Legion objects The results are returned to the daemon translated into an RPC reply and forwarded to the client Currently the Legion NFS process server daemon only works on Linux and Alpha Linux platforms Please contact us at lt legion help cs virginia edu gt if you need to run it on another architecture The infsd should be run locally You mustalso run lmountd with xpc 1mountd page 109 in order to mount Legion NFS Both of these daemons must be on the client Legion machine We recommend that you run them as root see S ecurity below for more information Security The two Legion NFS daemons 1n sdand 1mountd provide an NFS like file system while preserving Legion s stronger security features The NFS clientauthenticates itselfto 1n sd by passing the requesting user s Unix uid This authentication i
185. ove any context name associated with the object you mustuse the 1egion rmcommand to remove the object s name s or you will get binding errors You can use 1egion 1s Ato check for multiple context names The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_list_implementations vL c class context name 1 class LOID gt debug help Lists the implementation objects associated with the class named in class LOID gt 0r lt class context path gt In its default setting the output will consist of each implementation objects LOID and architecture type The following options are supported vL Run the command in a verbose setting The output will include byte size and a brief description of each object Legion will use one extra method invocation per implementation object debug Catch and print Legion exceptions help Print command syntax and exit legion_list_instances c lt class context name 1 class LOID gt debug help Displays information about the instances of the class named by context path or class LOID gt For every instance the tool displays the class s LOID current object address status active or inert the hoston which itresides and the vaultthatholds its OPR The example below shows that class BasicFileClass has two instances and that both are currently running legion li
186. owing options are supported function pattern Lets you use a Unix like wildcard argument to list specific functions You can use any of the standard wildcard patterns and 1 showLoids If Legion is unable to display a user s or group s context path it will print a LOID instead of unknown For example if you asked to see object home spw4s s ACL for all functions containing Mayl in their names you would see something like this legion show acl home legion MayI Access to Function 4MayI 6GetACL Allowed users Unknown users legion Denied Access to Function 4MayI 6S8etACL 23LRef AccessControlList Allowed Unknown users legion Denied Reference page 71 J une 19 2001 Legion 1 7 Reference Manual Access to Function 4AMayI 17LegionCheckAccess 30LRef LegionFunctionIdentifier 23LRef A ccessControlList 26LRef LegionCertificateSet i Allowed Empty Denied The results list each function s Al lowed and Denied list Notice that the third function s Allowed listis Empty This means that it contains an Empty Function set the default setting for all Legion object functions The Empty Function set contains the object s owner the admin User and the objects class These three objects are automatically given permission to call all of the object s functions Y ou can use 1egion change acl to change these lists page 62 page 72 Reference
187. p2 int amp foo int amp bar foo data data bar datatdata return footbar Simple Simple endif 6 2 Simple trans h and Simple trans c o Simple trans h Legion wrapper class definition for the Simple class ifndef H Simple trans finclude stdio h finclude legion Legion h include Simple h define SIMPLE OBJECT CLASS ID Simple define SIMPLE OP1 FUNCTION NUMBER 1 define SIMPLE OP2 FUNCTION NUMBER 2 oe class Legion Simple class Legion Simple private the object being wrapped Simple object For generating methodDone events virtual void generate MethodDoneEvent public Legion Simple Legion Simple wrapper member functions for each member function in object void Legion opl1 UVaL Reference LegionWorkUnit wu void Legion op2 UVaL Reference LegionWorkUnit wu Reference page 123 June 19 2001 page 124 Legion 1 7 Reference Manual auxiliary member functions needed virtual void enable functions LegionInvocationStore virtual int invoke method UVaL_Reference lt LegionWorkUnit gt wu virtual void accept member functions endif oe oe Simple trans c The wrapper class definition ifndef C Simple trans include lt stdio h gt include unistd h include legion Legion h include Simple trans h
188. particular file in the remote job s present working directory showscratch Printthe archive context scratch space If the run hasn t yet finished or if legion mpi run dies or is killed before the job finishes this space will contain oUT files that haven t yet been copied out class name binary local path name platform type help legion mpi run f option file n number of processors lt flags gt program class lt argl gt lt arg2 gt lt argn gt MP I implementation generally require that MP I executables reside in a given place on a disk Legion s implementation objects have a similar requirement This command registers the executables of different architectures for use with Legion s MPI It creates MPI specific contexts a class object and an implementation for the program and registers the name in Legion contextspace If Legion security has been enabled the newly created contexts will be placed in the user s home user name mpi context exceptifthe user is admin ornot logged in If Legion security has not been enabled the newly created contexts will be placed in the mpi context The command can be executed several times if you have compiled your program on several architecture The following option is supported help Print command syntax and exit lt flags gt Starts anMPI program The lt programclass gt argumentrequires the full context path for the class the class i
189. path see below The utility also monitors the application and reports if it dies Any application can be started with legion record but the command is most useful for Legion applications Only one execution ofthe application will be recorded in the storage file ata time If you record again to the same storage file you will overwrite previous data If you wish to use a Legion recorder objectto record your application s activity you must start the recorder object separately i e legion create object c class RecorderObject If you wish to record a server object i e one thatis not created by the client application but instead exists on its own you must start the server object in record mode independently of the client application The following options are supported name debug session name Specify a name for the debug session If this option is not used a random name will be chosen t interval S pecifies how long in seconds the legion record utility should wait between health checks These health checks are used to poll the Reference June 19 2001 legion replay uf local storage file gt 7c recorder context path name debug session name gt cmd lt debugger gt 10cal session number list debug help Legion 1 7 Reference Manual recorder objectto learn aboutobject death The default setting is 30 seconds debug Catch and print Legion exceptions help Pr
190. quired parameters flag Optional You do not have to include this in order to use the tool lt argument gt Required You mustinclude this in order to use the tool lt argument 1 gt lt argument 2 gt You must include one of these two arguments in order to use the tool You can use this argument or flag more than once when running the tool Please note that the sample outputs may not match your own Your system administrator may have customized your system s context space or limited what parts you can see In the interests of space most example LOIDs are shortened 1 You can also go to http legion virginia edu legion man html to see on line versions of the Legion man pages page 6 Reference J une 19 2001 Legion 1 7 Reference Manual 2 0 Command line functions 2 1 Calls on objects legion_configure_profile Edits information about your user profile security settings and fault tolerance settings Itis menu driven Hit the lt enter gt key to return to the previous menu level When you run this command you ll be given the following options 1 Edit Profile 2 Security 3 FaultTolerance The firstoption lets you edit your AuthenticationObjectto include your e mail address name and company The second option changes your security preferences forthe message layer You have the following choices 1 Off No encryption No digest 2 Protected Digested messages Encrypted credentials 3 Pri
191. rameters UVaL_Reference lt LegionLOID gt src UVaL_Reference lt LegionLOID gt dest int fnum int parms_to_expect UVaL_Reference lt LegionComputationTag gt tag UVaL_Reference lt LegionParameterList gt plist UVaL_Reference lt LegionContinuationList gt IcontList UVaL_Reference lt LegionEnvironment gt lenv The LegionMessage constructor creates a LegionMessage from the constituent parts passed as parameters Accessor functions LegionMessage exports public member functions to get and set all of its constituent parts Overloaded operators The equality operators and are overloaded Two LegionMessages are deemed equal only if each of the constituent parts are equal as determined by the equality operators of their respective classes show Parameters None Prints the contents of the LegionMessage to the stderr stream int pack int unpack Parameters LegionBuffer amp lb LegionMessage s packable 7 5 1 LegionParameter LegionParameter Parameters int param_number UVaL_Reference lt LegionBuffer gt Ib Constructs a new parameter whose value is assumed to be in 1b and whose number is set to param_number page 138 Reference J une 19 2001 Legion 1 7 Reference Manual Other constructors The default constructor creates a parameter with a negative parameter number and an empty LegionBuffer A constructor that takes only a LegionBuffer as a parameter unpacks the contents of the LegionParameter from that buffer Th
192. rap host start up host internal tools legion accounting info pusher legion init Apps security legion init Extra security legion init HPC security legion init SDK legion init SDK security legion make backend legion modify schedule legion mplfront legion native mpi backend legion native mpich wrapper legion native mpiibm wrapper legion native mpisgi wrapper legion native mpiultra wrapper legion permit user legion probe object legion translate arch legion vrun kill legion vrun run legion watch process invoke method L Legion documentation legion accounting info pusher legion make backend legion modify schedule 152 158 159 153 155 142 186 188 186 187 187 185 188 119 119 120 120 120 120 117 117 117 117 117 117 117 117 117 118 118 118 118 118 118 118 118 118 118 118 122 117 117 117 Reference Legion 1 7 Reference Manual page 211 J une 19 2001 legion mplfront legion native mpi backend legion native mpich wrapper legion native mpiibm wrapper legion native mpisgi wrapper legion native mpiultra wrapper legion permit user legion probe object Legion Simple legion translate arch legion watch process LegionBuffer associated LegionCompressor associated LegionE ncryptor associated LegionP acker associated LegionStorage constructors LegionB uffer LegionP ackable show LegionCompressor compress decompress LegionComputationTag accessor functions constructo
193. rbose w a lt arch gt h lt host gt block non block d ir lt dir gt D lt var value gt in contextfile out contextfile IN lt localfile gt OUT lt localfile gt stdin lt localfile gt stdout lt localfile gt stderr lt localfile gt novrun p robe lt localfile gt setscratch lt context gt meta lt option value gt f options file gt program class argl lt argn gt The 1egion run command executes a single instance of a program associated with the program class specified in the program class argument Legion will randomly select a host to execute the program observing the restriction that only hosts with an acceptable architecture may be selected Arbitrary command line arguments may be specified for the remote program Any number of input and output files may be specified for a single execution of 1egion run i e the in out and IN OUT options can be repeated Please note that the t and n flags are deprecated as of version 1 8 Instead you can use meta nodes lt num gt for t and meta minutes lt num gt for n The following parameters are used with this command lt program class gt Specifies the program class of which an instance should be executed This program class should have been previously created with legion_register_program page 99 or legion_register_runnable page 99 The following optional parameters are suppo
194. rd You can setup an rhosts file for rsh oran authorized keys file for ssh to accomplish this see the rsh and ssh man pages for further information You can run Legion commands on a remote host using rsh or ssh once you set the proper environment variables For sh ksh or bash use REGION RSH rsh ssh EGION_RCP lt rcp scp gt export LEGION_RSH LEGION_RCP Forcsh use setenv LEGION RSH rsh ssh setenv LEGION RCP rcp scp Optional parameters do the following L lt SLEGION gt S pecify LEGION for host default is local LEGION value O lt SLEGION_OPR gt S pecify LEGION OPR for host default is local LEGION OPR value A LEGION ARCH Specify the architecture type for the host default is local LEGION ARCH value B path S pecifies the basename of the executable host program that will be started on the target host default is UnixHostObject Reference June 19 2001 legion startup local debug legion_startvault Legion 1 7 Reference Manual N context name gt Specify the context name for the host object default is hosts lt host name U lt user id gt Specify the user id for host default is Current user id C lt host class gt S pecify the context path of the host class to use defaultis class UnixHostClass debug Catch and print Legion exceptions help Print command syntax and exit help Starts
195. rictions which may include restrictions to hosts vaults or implementations This command also uses the given scheduler to schedule the instantiation Parameters NumObjects 2Number of object to vector instantiate CldType Flag indicating whether the ClassName parameter is a context path name or a LOID ClassName LOID or context path name of the class to instantiate HIdType Flag indicating whether the HostName parameter is a context path name or a LOID HostName LOID or context path name of the Host to restrict the instantiation to VidType Flag indicating whether the HostName parameter is a context path name or a LOID VaultName LOID or context path name of the Vault to which the instantiation is restricted IIdType Flag indicating whether the HostName parameter is a context path name or a LOID ImpIName LOID or context path name of the Implementation which the instantiation is restricted SIdType Flag indicating whether the SchedName parameter is a context path name or a LOID ImpIName LOID or context path name of the Scheduler to use when scheduling the instantiation Return Values NULL terminated array of LOIDs indicating the objects that were instantiated Each elementofthe array is a char which is the LOID of one object created Reference page 155 J une 19 2001 Legion 1 7 Reference Manual Error Return NULL User Responsibility User is responsible for free ing ea
196. rite the files named in the second field from its current directory In this case the registered program mustread FILE1 NEXT2 Crypt andsSalt File and write THEN3 and FILE4 When legion run multi is called on the registered program with the above specification file it looks for matching patterns usr localtmp dump pdblegs2 entin your local directory home an4m pictures 1egs2 gifin your Legion context These are sentas inputfiles forrun 1egs2 which generates two output files outputlegs2 in your local directory dssplegs21og in your Legion context Exception file The exceptions file is an addendum to the specification file Itspecifies additional switches for specific patterns This allows you greater flexibility and control when running large batches of jobs The information in the exceptions file is passed directly to legion_runor if you use the e flag to whichever command you have specified legion_run_multi command is essentially a script that calls multiple 1egion runs or whichever command specified Forexample suppose thatthe following jobs match the patterns in your specification file ABC DEFGH 123 9999 GIRAFFE The specification file already provides input output constant information for all of these jobs and command line flags provide additional instructions However you wish to fine tune these instructions forjustjobs DEFGH and 123 Inthe exceptions files you can specify these two jobs and give your additional i
197. rm of object attributes about the given collection The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Reference page 49 J une 19 2001 Legion 1 7 Reference Manual legion leave collection c collection context path 1 collection LOID gt c member context path 1 member LOID gt debug help t e This command removes the object named in member LOID Or member path from the collection named in collection LOID gt Or collection path The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_list_oprs lt vault context path gt 1 lt vault LOID gt debug help legion list sub col 1 collection Lists all OPRs currently stored in a given vault The output includes information about inert objects LOIDs OPA owner and status The following options are supported legion make schedule debug Catch and print Legion exceptions help Print command syntax and exit ections LOID gt c lt collection path gt List a collection s set of subcollections and queries c lt class context path 1 class LOID gt n number of nodes gt f specification file gt q lt query gt page 50 help This command creates a host file for running an instance of the class namedin
198. rs pack show unpack LegionE ncryptor decode encrypt LegionInvocationS tore any_ready any_ready_for_func enable_function get_return_value insert next matched next matched for func release all return values release return value set priority LegionLOID accessors is class is empty LegionLOID LegionLOID protected overloaded operators pack same_class_as set_field_size set_type show page 212 117 118 118 118 118 118 118 118 122 118 118 132 135 135 134 133 132 132 133 135 135 135 135 135 140 140 140 140 140 140 135 135 135 131 131 131 131 132 131 131 131 132 132 131 135 137 137 137 137 136 137 137 137 136 136 138 Reference Legion 1 7 Reference Manual J une 19 2001 unpack LegionMessage accessor functions LegionContinuationList LegionE nvironment LegionE nvironmentltem LegionMessage other fields overloaded operators pack show unpack LegionP ackable pack LegionPacker get ZZZ put ZZZ LegionParameter accessor functions LegionP arameter other constructors overloaded operators pack show unpack LegionP arameterList constructors find pack set operations show unpack LegionP rogramG raph add constant parameter add invocation add invocation parameter add result dependency execute get_value LegionS torage current_byte getMetaData linearize read
199. rs SomeUser tallow users SomeGroup Note that you need full context paths for objects in the modifications parameter Thenextexample changes SomeContext s ACL Itdenies SomeUser and allows SomeGroup the right to call any function with multiLookup in it legion change acl home legion SomeContext multiLookup deny users SomeUser tallow users SomeGroup c lt object context name 1 object LOID gt l target owner LOID gt c target owner context path debug help Changes an objects owner This command currently works only on unclaimed objects if an objectis already owned you would have to be Reference page 63 June 19 2001 Legion 1 7 Reference Manual logged in as both the currentownerand the target owner in order to run this command The following options are supported v Run this command in verbose mode r Run this command in recursive mode If the specified object LOID gt Or object context path is a class ownership of all instances sub instances etc wil change If the specified object LOID gt or object context path refers to a context object change ownership of all context entries recursively applying the operation to sub contexts will change In either case ownership ofthe rootobjectreferred to by object LOID Or object context path is changed debug Catch and print Legion exceptions help Print command syntax and exit legion_
200. rted debug Catch and print Legion exceptions help Print command syntax and exit v erbose Run command in verbose mode page 100 Reference J une 19 2001 Legion 1 7 Reference Manual w S pecifies that the set tty object should be used If no tty object has been set the flag will be ignored If you have not created and seta tty objectfor your current window you will notbe able to see the command s output and an error message will appear Please see AboutLegion tty objects on page 75 in the Basic User Manual for more information a lt architecture gt Allows users to specify what kind of architecture the program should be executed on h host context path S pecify a remote host to run the program non block S pecify thatthe 1egion run command be nonblocking That is once it starts your program on the remote host it will exit and free up your command linet This command s default setting is to block block Specify that the 1egion run command block This is the default setting when you run it the command will continue to run at the command line until the remote job is finished d ir remote host directory S pecify that the program run on a specified directory on the remote host D var value Set environment variable var with value and run in context path name gt Copy the specified Legion file objectinto the remote program s current working directory before execut
201. s Parameters ParmName The name of the implicit parameter to which the action is being applied Value The integer value to be placed into the parameters Return Values 0 on Failure 1 on Success User Responsibility None int MethodlImplicitParm InsertString char ParmName char Str Insert a new string implicit parameter into the implicit method parameter database Parameters ParmName The name of the implicit parameter to which the action is being applied Str The new String to add to the database Return Values 0 on Failure 1 on Success User Responsibility None int MethodlmplicitParm Remove char ParmName Remove an implicit parameter from the implicit method parameters database Parameters ParmName The name of the implicit parameter to which the action is being applied page 192 Reference J une 19 2001 Legion 1 7 Reference Manual Return Values 0 on Failure 1 on Success User Responsibility None char MethodlmplicitParm FindLOID char ParmName Find an implicit parameter in the implicit method parameters database this parameter must be a LOID parameter Parameters ParmName The name of the implicit parameter to which the action is being applied Return Values The string representation of the LOID that was found Error Return NULL User Responsibility The user is responsible for free ing the returned LOID when done int MethodlmplicitParm Findlnt char Parm
202. s 70 legion set message security 70 legion set scheduler 54 legion set scheduler policy 54 legion set tty 35 legion set varch 55 legion set vault 20 legion set vrun 55 legion set worm 12 legion setup state 41 legion show acl 71 legion shutdown 41 legion shutdown class 41 legion skcc set class vaults 7 11 legion_skcc_set_defaults 7 11 legion_starthost 42 legion_startup 43 119 legion_startvault 43 legion_stateless_add_workers 78 page 206 Reference J une 19 2001 legion stateless configure legion stateless remove workers legion synch vaults legion tty legion tty off legion tty redirect legion tty unredirect legion tty watch legion unset worm legion update accounting db legion update attributes legion update stat tree legion vault host list legion version legion wellknown class legion whereis legion whoami Constructors context space documentation cp E enable_functions F fault tolerance changing SKCC settings G getinterface grid library attributes AddAttribute AddAttributes Getlnterface RemoveAttribute RemoveAttributes RemoveAttributeS ig RemoveAttributeS igs ReplaceAttribute ReplaceAttributes ReplaceAttributeS ig ReplaceAttributeS igs RetrieveA llAttributes RetrieveAttribute RetrieveAttributes RetrieveAttributeS ig RetrieveAttributeS igs C type manipulation CreatelnstanceP lacementlnfo CreateLegionHostR eservation CreateLegionVaultR eservati
203. s created through legion_mpi_register if you have not previously registered the program you ll need to do so before you can run it Parameters used for this command are f lt option file gt Allows users to start multiple MPI applications via an option file All applications must be registered with Legion and have a common MPI COMM WORLD n number of processors Specify the number of processors on which the program will run Reference page 85 J une 19 2001 Legion 1 7 Reference Manual Supported 1ags are v Verbose option up to four can be specified for increased detail h host set context Specify a set of hosts on which the program will run The context path should notresolve to a single hostbutto a context containing the names of one or more hosts Y ou ll need to create itby hand In the default setting Legion will pick a compatible hostand try to run the object If this fails Legion will try another compatible host HF local specification file Use a specification file in your local file space to schedule objects from the current execution see page 89 for more information hf Legion specification file Use a specification file in context space to schedule objects from the current execution see page 89 for more information in Legion input file Tells Legion to copy the contents of a Legion file objectto a file in the remote program s current working directory before execut
204. s logs out a user out of Legion This command removes the credentials file thatis created by the legion_login utility and has the effect of logging the user out of a secure Legion system We strongly recommend that users insert this command into a logout file or some other scriptthatis run when a userlogs out This ensures that credential files do notremain in the system for unnecessarily long periods The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Reference June 19 2001 Legion 1 7 Reference Manual legion_modify_parameters debug help argument Allows a user to modify the implicit parameter set for his or her current session These parameters can include anything the user wishes to place in them but usually include the user s credentials obtained when he or she logged in to their Authentication object The argument parameter must contain one of the following 1 p lt param type gt lt param name gt d lt param type gt param name gt lt param value gt a lt param type gt lt param name gt param value If you use p d or a in your argument lt param type gt mustbe one of the following values STRING PARM A string parameter FUNCTIONID PARM A parameter describing a function identifier INT PARM An implicit parameter containing an integer value LOID PARM An implicit parameter containing a valid LOID The following opti
205. s predicated on trust between the client s kernel and thus NFS and the NFS daemon in this case 1nfsd The interface between the NFS kernel client and 1nfsd follows NFS protocol 12 Legion NFS mount relies on the mount and umount Unix command line utilities Please see the associated man pages for information aboutusing these tools For more information aboutNFS mounts youcanalsosee the exports mountd andnfsd man pages The two Legion NFS mountdaemons and supporting materials were derived from the Unix User Space NFS Server Version 2 2 Key contributors authors were Mark Shand Don Becker Rick Sladkey and Olaf Kirch Reference page 111 June 19 2001 page 112 Legion 1 7 Reference Manual We recommend that 1n sd run as root Both 1infsd and l1mountd are responsible for bridging semantic differences between Unix and Legion security mechanisms and must translate a Unix uid to Legion credentials Users mustbe logged in with the 1egion login page 68 utility to access objects in a secure Legion system This utility creates a session file corresponding to a Unix uid in users local tmp directory An object s ACL list determines who has access rights to the object In an NFS mounted Legion system once a Unix uid has been mapped to Legion credentials access to Legion objects is authenticated and authorized via Legion mechanisms This prevents unauthorized access to the objectthrough Unix We expect that the daemons will execute wi
206. sage k Kill the job job owner and system administrators only cp priority Change the job s priority Reference June 19 2001 legion manage queue help purge maxrs lt slots gt legion_mpi_debug Legion 1 7 Reference Manual fr Force the job to restart job owner and system administrators only nc No file clean up q context path Specify a J obQueue object Default is etc JobQueue q context name gt Use this command to manage a Legion J obQueue object If you run it without flags you will see all jobs that the objectis currently managing If you are a system administrator you can also use the maxrs flag to set the maximum number of job slots and the purge flag to kill all of the object s jobs The following options are supported help Print this help message purge Kill all jobs reset queue system administrators only maxrs slots Set number of total run slots system administrators only q context path Specify queue object Default is etc JobQueue q c program instance context help A utility program thatallows the userto examine the state of MPI objects and print out their message queues The program instance context is the context that is holding your program s instances Normally it is mpi instances lt program_name gt home lt user_name gt mpi instances lt program_name gt in a secure system unless you specified otherwise when you s
207. slations The example shows the C class its translation and a sample program that illustrates how we invoke methods To write the translation we first define a wrapper class called Legion Simple This wrapper contains a protected data member an object of the translated C class We call this the wrapped object Foreach wrapped object member function we define a corresponding member function in Legion Simple The Legion Simple member functions job is to take a work unit build a corresponding call to the wrapped objects member function execute the call and package up any return values Legion Simple has additional member functions that figure out which wrapper member function should be called invoke method indicate to the invocation store which member functions will be accepted enable functions and perform the server loop accept member functions 6 1 Simple h and Simple c Simple h Avery simple class definition ifndef H Simple define H Simple include lt stdio h gt class Simple int data public Simple Simple int opl int foo int op2 int amp foo int amp bar endif Simple c Avery simple class definition ifndef C Simple define C Simple page 122 Reference June 19 2001 Legion 1 7 Reference Manual include lt stdio h gt include Simple h Simple Simple data 0 Simple opl int foo data foo int Simple o
208. something like this legion set vrun hosts my T3E SLEGION src T3E SDSC This tells Legion thatthe scripts are in LEGION src T3E SDSC The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_vault_host_list c vault context path 1 vault LOID gt a d t hosti lt host2 gt lt hostn gt 7p debug help Display and manipulates the list of hosts with which the vault named in lt vault context path gt or lt vault LOID gt can interoperate Note thatif you name the vault by its context name in the first parameter i e myVault you must use the hosts context names in the lt host1 gt lt host2 gt lt hostn gt parameter Similarly if you name the vault by its LOID with the 1 flag you must use the hosts LOIDs To view the list of hosts thata given vaultcan operate on you could use something like the example below legion vault host list vaults VaultName p COMPATIBLE HOST LISTING AK 1 01 07 d49d1a40 000001 c0c04724 iid 1 01 07 d59d1a40 000001 c094e23c AX 1 01 07 d69d1a40 000001fc0b68108 Reference page 55 June 19 2001 page 56 Legion 1 7 Reference Manual The following optional parameters are supported 1 a d t P debug help Use LOIDs to specify vault and host Add named host to the vault s acceptable host list Delete named ho
209. st from the vault s acceptable hostlist Test whether or nota hostis on the vault s acceptable host list Display the vault s acceptable host list Catch and print Legion exceptions P rint command syntax and exit Youcanusethe a a and t flags more than once when running the command but regardless of how you list them on the command line Legion will process themin a specific order when you run the command first adding any new hosts then deleting old hosts then testing any hosts and finally printing out the results Reference June 19 2001 Legion 1 7 Reference Manual 2 General functions about the state of the system legion classof c lt object context name l object LOID gt debug help Displays the LOID ofthe class ofthe objectnamedin context path Or object LOID gt The example below displays instance Foo s class LOID legion classof Foo The class of 1 01 66000000 01000000 000001 c0 is 1 01 66000000 000001 c0408552c33 The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_create_stat_tree base context path debug help Creates a database of current loads on all host objects in a system The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion get accounting data v help debug lt pull sourcel gt lt pul
210. st instances class BasicFileClass Class 1 01 66000000 000001fc0d63e97 knows about the following instances LOID 1 01 66000000 01000000 000001f c0a00 Current oa Xxx Xxxx Xxxx xxx 2020 Current host 1 01 07 30232908 000001 fc0 Reference page 17 June 19 2001 Legion 1 7 Reference Manual Current vault 1 01 03 2e232908 000001fc0 Status object running LOID 1 01 66000000 02000000 000001f c0edd Current oa XXx XXX XXX Xxxx 1895 Current host 1 01 07 31232908 000001 fc0 Current vault 1 01 03 2e232908 000001fc0 Status object running The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_refresh_local_cache Manually refresh some high use objects bindings and high use contexts LOIDs in your current login session legion_set_backup_vaults c lt instance context path gt 1 lt instance LOID gt nodeac tivate a d c vaultl context path l vaultl LOID gt a d c lt vault2 context path 1 vault2 LOID gt a d c lt vaultn context path l vaultn LOID gt Cv lt vault context path gt n lt total number of vaults gt page 18 Specify one or more backup vaults for an instance Use legion_skcc_set_class_vaults to set backup vaults fora class page 11 Backup vaults are used to replicate an object s persistent state the object s persistentstate
211. start l x lt exceptfile gt a rch lt architecture gt lt argl gt lt arg2 gt page 104 f ile lt specfile gt t ime lt timefile gt program class lt argn gt This command runs a previously registered serial program named in lt program class name gt with all of the different input files using a simple specification file named in specification file name gt to describe the names of the expected input and output files You must provide the number of processors and or a schedule file Before you run this command you must have registered the program name and created a specification file The specification file format is keyword filename pattern You must fill in all three fields on each line One file per line Specification file The first field the keyword provides information about the file named in the second field Possible keywords are IN in OUT out CONSTANT constant and stdin stdout stderr The case determines the file s location except for std constant in out Legion context space CONSTANT IN OUT local file space stdin stdout stderr The CONSTANT constant keywords indicate identical input for multiple runs e g input thatis used foreach run such as a password The std keywords refer to local files thatstdin stdout and stderr use A separate stdout and stderr are created for each run If you do not indicate a stdout file standard output will be sent to
212. syntax and exit For more information please see Independent programs on page 36 in the Basic User Manual legion register runnable program class executable path legion arch debug help The legion register runnable command is similar to the legion register programcommandin thatitallows programs to be registered for execution through the 1egion run utility However whereas the 1egion register program toolis used to register independent programs 1egion register runnable is used to register Legion linked programs programs that are linked against the Legion libraries and export the runnable object interface The following parameters are used with this command program class The Legion context space path of the class with which the registered program should be associated Reference page 99 J une 19 2001 Legion 1 7 Reference Manual executable path The local file path of the executable program to register This program should be a valid Legion object implementation that has been linked with the Legion library and thatexports the Legion runnable interface legion arch The platform type on which the program should be executed The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit For more information please see Legion linked programs on page 37 in the Basic User Manual legion run help debug v e
213. syntax and exit legion_shutdown_class c class context name 1 class LOID gt debug help Deactivates the class object named in lt class LOID gt Or context path and all of its instances This command operates recursively if applied to a metaclass for example it would deactivate the metaclass all of its class instances all of their instances etc Reference page 41 June 19 2001 legion starthost L lt SLEGION gt B lt path gt lt new host name gt debug help page 42 AN Legion 1 7 Reference Manual The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit O lt SLEGION_OPR gt A lt LEGION_ARCH gt N context name gt U user id gt C host class gt lt compatible vault list gt Creates a new host object on the specified lt new host name gt using the legion_create_object_r command page 15 automatically invoked on the host class The new host name gt is the host s DNS name The legion starthost command selects the following default values for the new object LEGION OPA LEGION_OPR Host HOST OPA binary path LEGION bin LEGION ARCH UnixHostObject This command uses remote shell rsh or ssh classes to start a new host object on a specified host Please note that you must be able to run rsh ssh on the target host from your current machine without having to enter a passwo
214. t debug This command sets native MPI properties on a host The following options are supported wrapper Specify a wrapper script that locates mpirun on the host The default specifies the legion native mpich wrapper script which is for an MPICH implementation debug Catch and print Legion exceptions help Print command syntax and exit legion_native_mpi_init lt architecture gt debug This command installs the 1egion native mpi backend class in a native MPI host The following options are supported architecture Specify an architecture for which an implementation for this class can be registered debug Catch and print Legion exceptions help Print command syntax and exit legion_native_mpi_register lt class name gt lt binary path gt lt architecture gt help Register a native MPI program with your Legion system The example below registers myMPIprograms charmm the binary path as using a Linux architecture legion native mpi register charmm myMPIprograms charmm linux You can run register a program multiple times perhaps with different architectures or different platforms If you have not registered this program before this will create a contextin the currentcontext path the context s name will be the program s class name in this case charmm and registers the name in Legion context space The following option is supported help Print command syntax and exit
215. t a BindingAgent User Responsibility None int isMPI LegionldType IdType char ObjName Determines if the indicated object is a MPI object or not Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to test Return Values 1 if the objectis a MPI 0 if the objectis nota MPI Reference page 167 J une 19 2001 Legion 1 7 Reference Manual User Responsibility None int isPVM3 LegionldType IdType char ObjName Determines if the indicated objectis a PVM3 object or not Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to test Return Values 1 if the object is a PVM3 0 if the object is nota PVM3 User Responsibility None 8 5 Legion attributes The following functions deal with the attribute database that all Legion objects support int AddAttribute LegionldType ldType char ObjName char Attribute Add an attribute to an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the objectto which the attribute is to be added Attribute The string representation of the attribute to add to the database This is of the form attribute signature attribute value Return Values 1 on Success 0 on Failur
216. t gt wu switch wu get function number case SIMPLE OP1 FUNCTION NUMBER Legion opl wu break case SIMPLE OP2 FUNCTION NUMBE Legion op2 wu break default fprintf stderr Legion Simple invoke method Nin fprintf stderr This object does not export function number d n wu get function number exit 0 break W This is the server loop EventMgr serverLoop continuously flushes events and then blocks waiting for events to become available void Legion Simple accept member functions LegionEventManagerDefault serverLoop 7 Enable the wrapped object s functions The LIS must be explicitly told which functions to accept There will eventually be some object mandatory functions in here too void Legion Simple enable functions LegionInvocationStore LIS Enable the function numbers that I can handle LegionInvocationStoreLL Default enable function SIMPLE OP1 FUNCTION NUMBER DEFAULT PRIORITY LegionInvocationStoreLL Default enable function SIMPLE OP2 FUNCTION NUMBER DEFAULT PRIORITY Register my event handler LegionEvent MethodReady addHandler LegionMethodInvoke 1 0 Reference June 19 2001 6 3 exl Simple c Legion 1 7 Reference Manual This is the event handler that get calledona
217. t object context path gt If the tty object is not currently directing output to the named file the command is ignored P lease see page 75 in the Basic User Manual for a discussion of tty objects The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_tty_watch c tty context path 1 tty LOID gt debug help Causes output written to a Legion tty object to be printed to standard output If no command line parameters are specified the current tty object set for the shell session is selected Otherwise the tty object named in tty LOID gt Or tty context path is selected Note the command will not self terminate to stop the program send ita SIGINT i e using C or kill INT Any number of 1egion tty watch sessions may simultaneously watch the same Legion tty object Please see page 75 in the Basic User Manual for a discussion of tty objects Reference page 36 June 19 2001 legion 2drm file name Legion 1 7 Reference Manual The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit This command removes a 2D file object from Legion It differs from legion rminthatthe object s subfiles are removed as well Ifyou use legion rmto remove a 2D file object the object s subfiles will not be removed The following parameter must be included file name Local path of
218. t parameter to which the action is being applied Value The value of the integer parameter to replace lt ParmName gt with Return Values 0 on Failure 1 on Success User Responsibility None page 194 Reference J une 19 2001 Legion 1 7 Reference Manual int MethodlmplicitParm ReplaceString char ParmName char Str Replace an implicit method parameter in the database with another string parameter Parameters ParmName The name of the implicit parameter to which the action is being applied Str The string parameter which the user wishes to replace ParmName With Return Values 0 on Failure 1 on Success User Responsibility None int MessagelmplicitParm InsertLOID char ParmName char Loid Insert a LOID implicit parameter into the implicit message parameters Parameters ParmName The name of the implicit parameter to which the action is being applied Loid The string representation of the LOID to be added Return Values 0 on Failure 1 on Success User R esponsibility None int MessagelmplicitParm InsertInt char ParmName int Value Insert an int implicit parameter into the implicit message parameters Parameters ParmName The name of the implicit parameter to which the action is being applied Value The integer value to be placed into the parameters Return Values 0 on Failure 1 on Success Reference page 195 J une 19 2001 Legion 1 7 Reference Manual User Respons
219. t path of the collection object in question ConstituentIDType A flag to show if ConstituentName is a LOID or a context path ConstituentName Eithera LOID ora context path for the object whose collection data is being updated Attributes NULL terminated array of object attributes Return Values 0 on Failure 1 on Success User Responsibility None page 200 Reference J une 19 2001 Legion 1 7 Reference Manual CLegionCollectionData QueryCollection LegionldType CollectionldType char CollectionName char QueryString Retrieve a list of queried information from the collection Parameters CollectionIDType A flag to show if CollectionName is a LOID or a context name CollectionName Either the LOID or the context path of the collection object in question QueryString A MESSIAHS style query string Return Values A NULL terminated list of CollectionData entries Error Returns Returns NULL on failure User Responsibility User is responsible for destroying the individual elements returned as well as for free ing up the array ifdef_cplusplus fendif endif Reference page 201 J une 19 2001 Legion 1 7 Reference Manual 9 0 Error messages The CError h file contains the declarations for the error reporting mechanism used in the C Library interface to the Legion system Below are the identifiers and their codes
220. t would be called impls my class linux 2 You can use the c lt object context path flag to specify a different context path or the nc flag to specify thatno context path be assigned At the moment possible architecture values are solaris Sun Workstation S olaris 5 7 or later e sgi n32 SGI Workstations IRIX 6 5 n32 build or later n32 build sgi n64 SGI Workstations IRIX 6 5 n64 build or later n64 build linux x86 Red Hat 6 x Linux alpha linux DEC Alpha Red Hat Linux 6 x alpha DEC DEC Alpha OSF1 v4 e rs6000 IBM RS6000 AIX 4 3 hppa hpux HPUX 11 x 3 The HPUX 11 platform is available upon request We will include an HPUX 10 platform in a future release Reference page 23 June 19 2001 Legion 1 7 Reference Manual 90 Cray T90 Unicos 10 x 4 t3e Cray T3E Unicos mk 2 x The following optional parameters are supported c context path S pecify a context path forthe new object Defaultis impls binary name arch f nc S pecify that the new object have no context name v Run the command in verbose mode a lt attribute gt Assign the new object an extra attribute debug Catch and print Legion exceptions help Print command syntax and exit legion_generate_domain_cookie o cookie output filename gt debug help legion init arch debug help Generates a domain cookie file for the current Legion domain as required by 1egio
221. tParm ReplaceString char ParmName char Str Replace an implicit message parameter in the database with another string parameter Parameters ParmName The name of the implicit parameter to which the action is being applied Str The string parameter which the user wishes to replace lt ParmName gt with Return Values 0 on Failure 1 on Success User Responsibility None 8 12 Collections The following section contains the functions which allow a program to manipulate update and query Legion collection objects page 198 Reference J une 19 2001 Legion 1 7 Reference Manual int JoinCollection LegionldType Collectionld Type char CollectionName LegionldType JoinerldType char JoinerName J oin an object into a collection Parameters CollectionIDType A flag indicating whether CollectionName is a LOID or a context name CollectionName Either the LOID or the context path of the collection object in question J oinerlDType A flag indicating whether J oinerName is a LOID or a context path J oinerName Either a LOID ora context path for the object being added to the collection Return Values 0 on Failure 1 on Success User Responsibility None int JoinCollection_wData LegionldType CollectionldType char CollectionName LegionldType JoinerldType char JoinerName char Attributes J oin an object into a collection and give init data Parameters CollectionIDType A flag indicating w
222. tain any spaces or begin with an uppercase letter Optional parameters do the following a newattribute Add an attribute d attribute Delete an attribute r oldattribute new attribute Replace an attribute debug Catch and print Legion exceptions help Print command syntax and exit The following example adds the attribute color red blue to object Foo with the a flag Reference J une 19 2001 Legion 1 7 Reference Manual legion update attributes Foo a color red blue legion update attributes Added 1 attributes s to object Similarly you can remove attributes with the a flag Note however that if you must provide all of an attribute s parameters legion update attributes Foo d color red legion update attributes Warning Deleted 0 attributes s from object instead of 1 specified legion update attributes Foo d color red blue legion update attributes Deleted 1 attributes s from object Reference page 13 J une 19 2001 Legion 1 7 Reference Manual 2 2 Calls on class objects legion activate object c lt object context name l object LOID gt debug help Activates the object named in object LOID Or context path i e instantiates that object as a process if itis inert If the object is already active the command has no effect The following options are supported debug Catch and print Legion exceptions help Pri
223. tandard error novrun Do notrun on a virtual host l e disable use ofthe virtual architecture on virtual hosts The remote program will run on the physical architecture for the selected host This option is usually not appropriate for user tasks Warning the registered implementa tion for the virtual architecture of the selected hostshould be usable on the phys ical architecture of the selected host e 9 a script meta option value Specify metaoptions for the run These options may be meaningful only for certain combinations of jobs and machines Listed below is the set of supported options and their meaning nodes min max Numberofnodes forjob default is 1 tasks_per_node lt num gt Number of tasks per node default is 1 Total number of tasks is product of allocated nodes and tasks per node queue name Name of a queue on host priority lt str gt Priority to run under minutes lt num gt Duration of run Reference J une 19 2001 Legion 1 7 Reference Manual p robe lt local file name gt Store the remote job s tracking name in a file on your local host You must use this option if you wish to use the legion probe run tool setscratch context path S pecify a portion of your contextspace to be used as scratch space f option file Allows users to specify options for running legion run in a separate file rather than listing them on the command line This is useful for programs
224. tarted the program i e if you used the p flag when youran 1egion mpi run This command will return a list of all of the program s instances and what each one is doing This is a handy way to debug a deadlock The following option is available with this command q List the contents of the queues help Print command syntax and exit If you use q the command will return a listofinstances thatare waiting to be received by the queues There are a few limitations if an MPI object doesn t respond the command will hang and not go on to query additional objects An MPI object can only respond when it enters the MPI library if it is in an endless computational loop it will never reply Output goes to stdout Reference page 83 June 19 2001 legion mpi probe help debug Legion 1 7 Reference Manual v erbose all list in context path name gt out context path name gt IN lt local file name gt OUT lt local file name gt showscratch stat lt remote file name gt lt pid context name gt page 84 Checks an MPI program started on a remote host with legion_mpi_run page 85 This command resembles legion_probe_run page 96 in that you can check on jobs move inputand outputfiles between your local and execution hosts Itdoesn t use a probe file however since you can contact your job through its pid context The following parameter must be used pid c
225. tered they are skipped and legion_cp prints a warning message Note that recursive mode automatically detects cycles in context space and prevents the recursive copy from revisiting context nodes in the cycle A warning message is printed in the event that cycles are detected Local source mode Use to indicate that the file or directory to be copied lt source path gt is in the local file system By defaultthe lt source path gt is assumed to be in Legion context space Local destination mode This option indicates that the lt destination path gt is in the local file system The path is assumed to be a Legion context path Specify a vault restriction for new objects created by this command Supply the context path of the vaultthat should manage new objects created as legion_cp runs Match class mode This mode indicates that when files or contexts are created by this command they should match the class of their source context or file By default new files and contexts are created using the default file and context classes for your current Legion environment This mode can only be used when copying within Legion context space i e without 1ocalsrc Or 1ocaldest Print out the size transfer time and transfer rate for each file copied J une 19 2001 Legion 1 7 Reference Manual debug Catch and print Legion exceptions help Print command syntax and exit legion_deactivate_instances stay_down debug
226. ters Name The path to remove from context space Return Values 1 on Success 0 on Failure User Responsibility None char ContextSingleReverseLookup LegionldType ldType char ObjName Try and obtain a context path name for a given object This command uses the object s attributes to determine this name and only returns the first name found Note that the attribute database may or may not actually reflect the object s actual context space names Parameters IdType Indicates whether the ObjName gives a context path name or a LOID ObjName Either the context name or the LOID of the object to reverse lookup Return Values First context path name of the object looked up Error Return NULL User Responsibility The user is responsible for free ing the name returned char ContextMultiReverseLookup LegionldType char ObjName int MaxNum Try and obtain a list of context path names for a givenobject This command uses the object s attributes to determine these names and only returns the first MaxNum entries found Note that the attribute database may or may not actually reflect the object s actual context space names page 150 Reference J une 19 2001 Legion 1 7 Reference Manual Parameters IdType Indicates whether the ObjName gives a context path name or a LOID ObjName Either the context name or the LOID of the object to reverse lookup MaxNum Maximum number of entries to return Return Valu
227. text path Or tty LOID gt Note thatthis command can only be invoked on objects that have dynamic output redirection enabled If the command is invoked on an objectthat does not have redirection enabled neither the object nor the tty is affected and an error message is displayed The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Reference page 29 J une 19 2001 Legion 1 7 Reference Manual legion export dir v help noserver autorehash local directory path target context path Theiegion export dir command allows a complete directory tree in the local file system to be temporarily linked into Legion context space A new context is created to replicate the local directory tree in contextspace The files contained in the shared directory are copied in to Legion objects in the new context The new contextobjects have the same names as the original files For example if the local directory contains three files called foo txt foo doc and foo c the new context will contain three Legion objects called oo txt foo doc and LOO The command executes for as long as you wish if you pause the command the tree s context space will not be available Once you resume the command the context will again be available To pause the command run 1egion export dir quit below or if the command was started in noserver mode press c To resume using t
228. text to update The default starting point is sites collection collection context path Specify a collection to satisfy host information requests The default is etc DefaultCollection Reference page 59 J une 19 2001 legion version debug help Legion 1 7 Reference Manual Prints your Legion version number For example the output below indicates thatthe currentsystem is University ofVirginia Legion version 1 5 9 legion version VaL Legion version 1 5 9 The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_wellknown_class lt wellknown class name gt debug help Gets the class LOID ofa Legion well known class P ossible values for wellknown class are e LegionClass e BootstrapMetaClass UnixHostClass UnixVaultClass e CommandLineClass e ContextClass e ImplementationClass e UnixlmplementationC acheClass e BindingAgentClass The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_whereis c lt object context name gt l1 object LOID gt debug page 60 help This command returns a specified object s host and vault object That is the output gives the context path ofthe hostand vault objects where the object and the object s persistent state are located If the host or vault objects have been ass
229. tfor Empty Function In this setting only the object s owner the admin user and the object s Reference June 19 2001 legion change owner v r Legion 1 7 Reference Manual class can call the function When you change the object s permissions for one or more functions the setof allowed or denied users is merged with the Empty Function list That is if you add user John to the Allowed list for object Foo s getInterface the list will now contain four users you the owner admin Foo s Class and John The following parameters are required function pattern Lets you specify a Unix like wildcard argument that indicates which functions should be modified Can contain any standard wildcard pattern e g and modifications A listof statements that add remove users or groups from the specified functions for the specified Legion object It can contain these elements allow allow deny deny l lt user group LOID gt c user group context path gt Legion checks the Denied list before it checks Allowed so if a user or group is on both lists Legion will consider it denied You can list multiple modifications ina single run For example you can alter SomeFile s ACL to allow SomeUser and SomeGroup to call any functions with read in them such as read hosts contexts Orget ready time legion change acl home legion SomeFile read tallow use
230. th root privileges on the clients host and will accept access only from privileged ports Assuming that root and root privileged processes including the NFS kernel client are not compromised 1n sd and mlountd are secure from malicious attacks File handles are never exposed on the wire If a malicious remote user becomes root on the client host and impersonates a valid user by using a valid uid on an NFS request he may attemptto subvert 1n sd via a bogus RPC request These type of attacks are avoided by cryptographically signing file handles A malicious user may also attemptto subvert 1mountd However the daemon will only respond to the local host so a rogue user cannot obtain the file handle needed for subsequent transactions Legion uses fine grained ACLs forauthorization they record individual and group users abilities to invoke individual methods Translations between Legion ACLs and Unix permission bits are therefore lossy Individual methods must be classified as read write execute Or some combination of these in orderto correspond to Unix permission bits Legion provides a global name space including individual accounts which may not correspond to any particular Unix account on a local machine Legion does not assign group ownership to an object so objectownership and groups within a Legion NFS mounted file system do notdirectly adhere to Unix semantics A Legion object s owner may not hold an account on the client machi
231. that each job was checked when it was checked measured in seconds since anuary 1 1970 the status that was returned e g Started Error and if known the host that it was run on The file is in your local directory End switches for legion run multi Provide arbitrary command line arguments for the registered program The possible architectures that can be used with the a flag are limited Atthe moment they are Architecture Corresponds to Comments solaris Sun workstations running Solaris 5 x sgi SGI workstations running IRIX 6 5 linux x86 running Red Hat 6 x Linux alpha linux DEC Alphas running Red Hat 6 x Linux alpha DEC DEC Alphas running OSF1 v4 rs6000 IBM RS 6000s running AIX 4 2 1 hppa hpux HPUX 11 t90 Cray T90s running Unicos 10 x virtual hosts only see page 69 in the System Administrator Manual t3e Cray T3E running Unicos mk 2 x virtual hosts only see page 69 in the System Administrator Manual page 108 Reference June 19 2001 rpc lmountd f exports file local path exports file exports file local path gt debug lt facility gt port port number gt d P F n t Legion 1 7 Reference Manual foreground h help allow non root p promiscuous no spoof trace v version The Legion NFS mount daemon enables you to NF S mount a Legion file system to your lo
232. tions fora given object The output will include information about each invocation s status timing progress and errors The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit Prints information about a given object The output obtained from the objects class will include the object s host vault owner Object Address status etc Optional parameters do the following Reference J une 19 2001 Legion 1 7 Reference Manual v Print additional details about the specified object host machine name and context name OPA and vault context name debug Catch and print Legion exceptions help Print command syntax and exit legion_skcc_set_class_vaults SKCC class context path a d c vaultl context path I vaultl LOID gt a d c lt vault2 context path l vault2 LOID gt a d c lt vaultn context path l vaultn LOID gt Set an allowable set of backup vaults on which to store the specified SKCC class s replicated state This applies to all of the class s instances Backup vaults are used to replicate an object s persistent state the object s persistentstate is replicated and stored in multiple vaults when it is deactivated so that if its main vault crashes its state is still available However the replication policy synchronizes the object s state when the object deactivates if the main vault crashes while
233. tivate an inert Legion object using the indicated scheduler to schedule the activation Parameters OIlDType Flag indicating whether the ObjectName parameter is a context path name or a LOID ObjectName LOID or context path name of the object to activate SldType Flag indicating whether the SchedName parameter is a context path name or a LOID SchedName LOID or context path name of the scheduler to use when doing the activation Return Values 1 on Success 0 on failure User Responsibility None page 158 Reference J une 19 2001 Legion 1 7 Reference Manual int ActivateRestricted LegionldType OIDType char ObjectName LegionldType HIDType char HostName LegionldType VIDType char VaultName LegionldType IIDType char ImplName Activate an inert Legion object but subject to the restrictions indicated by the user Parameters OIDType Flag indicating whether the ObjectName parameter is a context path name or a LOID ObjectName LOID or context path name of the object to activate HIdType Flag indicating whether the HostName parameter is a context path name or a LOID HostName LOID or context path name of the Host to which the activation is restricted VIDType Flag indicating whether the VaultName parameter is a context path name or a LOID VaultName LOID or context path name of the Vault to which the activation is restricted IIDType Flag indicating whether the ImplName parameter is a context pat
234. ual 2 Login to the desired machine i e the machine which contains the host and or vault object that you wish to shut down 3 Set the user environment correctly see page 14 in the System Administrator Manual 4 Enter the legion_shutdown command with the local flag legion shutdown local The vault or host object will then shut down 5 3 Restarting extra hosts and vaults Once an extra host or vault has been safely shut down it can be restarted If the host or vault was not safely shut down you cannot restart it but must delete the OPR directory restart Legion and start the host or vault again see System restart pg 27 in the System Administrator Manual 1 Login to the machine on which the host or vault object resides 2 Setthe user environment please see page 14 in the System Administrator Manual 3 Run the start up command with the 1oca1 flag legion startup local Your local host or vault object now be running 5 4 Using two hosts to start up a system Generally you can use a single hostto starta new Legion system but if your machines are strapped for memory you may need to split the process between two hosts Technically you can use two hosts used for the whole procedure the start up host and the bootstrap host Figure 1 below start Legion from one host and use a different host as the bootstrap The start up host must always be used to run legion_startup The host that you
235. untd lmountd does not register with portmap this ensures that NFS RPC requests bound for NFS servers Or mount daemons are not inadvertently intercepted So while you do not have to specify a port this implies that you should F foreground Run 1mountd in the foreground If debugging is also requested it will be sent to stderr h help Print command syntax and exit n allow non root Allow incoming NFS mount requests to be honored even if they do not originate from reserved IP ports Please read the Security section of rpc Infsd page 111 before using this option p promiscuous Run in promiscuous mode so thatthe server will serve any host on the network This violates infsa s security premises so itis deprecated t no spoof trace By default 1mountd logs every access by unauthorized clients This option turns off logging of such spoof attempts for all hosts listed explicitly in the exports file v version Printthe currentversion numberofthe program Reference J une 19 2001 Legion 1 7 Reference Manual The daemon recognizes the following signals SIGHUP Causes lmountd to reread the exports file andany access restrictions in etc hosts allow and etc hosts deny If you have altered these files and wish your changes to take effect you must send SIGHUP to infsd as well SIGTERM Kills the daemon This is the preferred method since it allows proper termination of the object SIGUSR1 If 1m
236. usly been connected to another domain three cookie files would be listed legion combine domains LegionDomainCookie 35d82a07 LegionDomainCookie c8 Created 2 new domain interconnections legion create implementation binary path name architecture c class context name 1 class LOID gt c object context path gt nc v a lt attribute gt debug help Creates an implementation object based on the binary executable named in binary path name Each class maintains a list of the implementation objects that are suitable for its instances There are a setofimplementation objects created when yoursystem was initialized use legion 1s la impl to see a list Several different implementation objects might be maintained by a class to supportthe use of multiple platforms a class mighthave implementation objects fordifferentarchitectures for differentoperating systems with different memory requirements etc The new implementation object is associated with the class object named in lt class LOID Or class context path and is marked as usable for hosts ofa specified type linux solaris etc The sample below creates a new implementation objectfor my class legion create implementation Legion bin linux my class linux my class The new object is automatically assigned the context path impls my_class linux 1 ifyou ran the example a second time the new objec
237. v sec tv tv usec my instance number rand tv tv sec tv tv usec Initialize Legion Library Legion init Manufacture my own LOID because I m a command line object Legion SetMyLOID make loid UVaL CLASS ID COMMANDLINI my instance number IU Tellmy creator I m ready to go Legion AcceptMethods Create an empty program graph LegionProgramGraph G Legion GetMyLOID Create a couple of Simple objects UVaL Reference LegionLOID A name B name A name Legion CreateObject SIMPLE OBJECT CLASS ID B name Legion CreateObject SIMPLE OBJECT CLASS ID Get handles for each object LegionCoreHandle A handle A name B handle B name First call x A op1 a invoke s signature is invoke function num num parms num results UVaL Reference LegionInvocation invl invl A_handle invoke SIMPLE_OP1_FUNCTION_NUMBER 1 1 G add_invocation invl UVaL_Reference lt LegionParameter gt parml parml make_int_parameter a 1 G add_constant_parameter invl parml 1 Second call y B op1 b UVaL_Reference lt LegionInvocation gt inv2 inv2 B handle invoke SIMPLE OP1 FUNCTION NUMBER 1 1 G add invocation inv2 UVaL_Reference lt LegionParameter gt parm2 parm2 make int parameter b 1 G add constant parameter inv2 parm2 1 Reference June 19 2001 Legion 1 7 Reference
238. vate Encrypted messages E ncrypted credentials These will change the settings for messages passed by your objects We STRONGLY recommend that you read section 7 0 in the System Administrator Manual before using these options The third edits your fault tolerance settings for SKCC objects The options are 1 EditSKCC Policy default 4 backups per user 2 EditSKCC Policy default backups class wide class owner only 3 EditSKCC Vaults class owner only These affect your SKCC objects BasicFileClass ContextClass ImplementationO bject and UserAuthenticationO bject are the default SKCC objects Please see section 6 6 in the Basic User Manual for information on SKCC Note that these options will affect previous settings It uses the following commands to edit your settings legion skcoc set class vaults page 11 legion skcc set defaults page 11 legion set backup vaults page 18 legion class vault list page 46 Note thatyou cannotchange settings on objects thatyou do notown or have permission to edit If you are notthe class owner you can use the first option to set the default number of backup vaults for your SKCC objects Reference page 7 June 19 2001 Legion 1 7 Reference Manual legion_exports_interface c context name gt 1 lt LOID gt w well known class type f function signature gt debug help page 8 Creates an interface from the listof well known class
239. void DestroyLegionBinding CLegionBinding void DestroyHostObjectStatus CLegionHostObjectStatus void DestroyLegionOPRAddress CLegionOPHRAdaress void DestroyUVaL_InstanceRecord CUVaL_ nstanceRecora void DestroyInstancePlacementinfo C nstancePlacementlnfo void DestroyLegionCollectionData CLegionCollectionData All of the complicated C types that are indirectly represented here as typedefs to ints must be explicitly destroyed so that there destructors may be called To destroy an object of type xxx Call the Dest royxxx function on its C typedef Parameters All destroy functions take one parameter the variable of the given type to destroy Return Values NONE UserResponsibility NONE int HostReservationRecord GetStatus CLegionHostReservationRecora char HostReservationRecord_GetObjLoid CLegionHostReservationRecora int VaultReservationRecord_GetStatus CLegionVaultReservationRecora char VaultReservationRecord_GetObjLoid CLegionVaultReservationRecora Reference page 177 June 19 2001 page 178 Legion 1 7 Reference Manual CLegionHostReservation LegionReservation GetHostReservation CLegionReservation CLegionVaultReservation LegionReservation_GetVaultReservation CLegionReservation CLegionHostReservation CreateLegionHostReservation egionldType char HostName int identity int flags CLegionVaultReservation CreateLegionVaultReservation LegionldType char VaultName int
240. whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the objectto which the attribute will be added Attribute The string representation of the signature of the attribute to remove from the object s attribute database Reference page 171 J une 19 2001 Legion 1 7 Reference Manual Return Values 1 on Success 0 on Failure User Responsibility None int RemovedAttributes LegionldType IdType char ObjName char Attributes Remove a set of attributes from an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID ora context path name ObjName The context path name or the LOID of the object to which the attribute will be added Attributes A NULL terminated list of the string representations of the attributes to remove from the object s attribute database Return Values 1 on Success 0 on Failure User Responsibility None int RemoveAttributeSigs LegionldType ldType char ObjName char AttributeSigs Remove a set of attributes from an object s attribute database Parameters IdType Flag indicating whether parameter is a LOID or a context path name ObjName The context path name or the LOID of the objectto which the attribute will be added AttributeSigs A NULL terminated list of the string representations of the signatures of attributes to remove from the object s attribute database Return Values 1 on Succ
241. will return information about which log requests are currently being processed help Print command syntax and exit debug Catch and print Legion exceptions ot seconds Outcall timeoutin seconds defaultis 60 seconds it lt seconds gt Incall timeout in seconds default is 60 seconds legion_host_stats c host context path 1 host LOID gt debug help Prints the number of objects and currentload forthe given host object The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion list objects c host context path 1 host LOID gt debug help Lists the Legion objects currently managed by i e running on the host object named in host context path or host LOID gt This may include each object s LOID status and its owner s LOID and OA The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion update accounting db v local configuration file path local logfile directory page 58 Parse the data in all accounting information logs in a specified local directory and place the data into a MySQL database This tool requires the following system configurations in order to run properly Reference June 19 2001 Legion 1 7 Reference Manual Linux Unix variant operating system e Perl version 5 005 05 or higher A
242. wing options are supported f exports file exports file local path S pecify a local path forthe exports file Default is etc exports For security reasons the Legion NFS daemons are run locally so only the local host should be listed in this file In the future this will be mandatory and this option will be eliminated d debug facility Logoperations verbosely The current legal values for facility are call for logging RPC calls and arguments hcache for file handle cache operation and auth for authentication routines P port port number Specify a portnumber for infsd The default is 2049 Note that unlike a normal NFS server Infsd does not register with portmap this ensures that NFS RPC requests bound for NFS servers or mount daemons are not inadvertently intercepted F foreground Run intheforeground If debugging is also requested it will be sentto stderr h help Print command syntax and exit 1 1og transfers Try to catch all files retried from and written to 1n sd For each file stored or retrieved a single line containing the client s IP address and the file s name is written to the system log daemon Reference page 113 June 19 2001 page 114 Legion 1 7 Reference Manual n allow non root Allow incoming NFS requests to be honored even if they do not originate from reserved IP ports P lease seethe Security section on page 111 before using this option p pr
243. xported directory tree legion export dir rehash target context path To be usedin conjunction with 1egion export dir page 30 Tells the command to check the shared local directory for any changes and to update the shared context space accordingly The following parameter is required target context path A context path holding copies of an exported directory tree legion get host c object context name 1 object LOID gt debug help This command looks up and returns the LOID of the hoston which the object named in object context path or object LOID gt currently resides legion get host Foo 1 01 07 d49d1a40 000001 c0c04724 The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_get_vault c lt object context name gt 1 object LOID gt debug help Returns the LOID of the vault which the object named in lt object context path gt 0r lt object LOID gt is currently using to store its OPR The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_list_names c object context name 1 object LOID gt debug help Lists all of the given object s context names This includes names assigned by other users The following options are supported debug Catch and print Legion exceptions help Print command syntax and
244. xports interface class LegionClass i LegionLOID ping 1 legion exports interface hosts BootstrapHost V LegionLOID ping w UnixHostClass a The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_get_interfac c lt class context name 1 class LOID gt debug help Retrieves the interface ofa Legion object named by lt class LOID gt or context path by calling thatobjects get Interface member function Prints the returned interface to stdout The following options are supported debug Catch and print Legion exceptions help Print command syntax and exit legion_ping c lt object context name l1 object LOID gt timeout lt seconds gt debug help Calls the object mandatory ping member function on the object named in object LOID gt Ifthe command returns the objectexists in an active state and its LOID is displayed legion ping foo Pinging 1 01 66000000 14000000 000001 c0a72 Returned 1 01 66000000 14000000 000001 c0a72 If the objectis not accessible by the tool the command will return an error legion ping foo foo does not resolve to a valid loid in my context The following optional parameters are available timeout seconds The time out flag specifies a maximum number of seconds to wait for the ping to complete successfully If the
245. ype char ClassName LegionldType SIDType char SchedName Create a vector of new Legion objects by vector instantiating the given class Used the given scheduler to schedule this vector instantiation Parameters NumObjects Number of object to vector instantiate CldType Flag indicating whether the ClassName parameter is a context path name ora LOID ClassName LOID or context path name of the class to instantiate SldType Flag indicating whether the SchedName parameter is a context path name ora LOID ClassName LOID or context path name of the Scheduler to use when instantiating the class Reference page 153 J une 19 2001 Legion 1 7 Reference Manual Return Values NULL terminated array of LOIDs indicating the objects that were instantiated Each elementofthe array is a char which is the LOID of one object created Error Return NULL User Responsibility User is responsible for free ing each LOID in the array as well as the array itself char CreateRestricted int NumObjects LegionldType CIDType char ClassName LegionldType HIDType char HostName LegionldType VIDType char VaultName LegionldType IIDType char ImplName Create a vector of new Legion objects by vector instantiating the given class The user also indicates any combination of restrictions which may include restrictions to hosts vaults or implementations Parameters NumObjects 2Number of object to vector instantiate CldType Fl

page 85 - Legion - University of Virginia

Contents

Download Pdf Manuals

Related Search

Related Contents