Penn Computing

Penn Computing

Computing Menu Computing A-Z
Computing Home Information Systems & Computing Penn

Service Alerts


PennNames Client Commands



General instructions

In describing the PennNames client command set, all PennNames variables will be in UPPERCASE and enclosed in angle brackets. Text in lower case should be entered as is. Information in square brackets is optional and if you opt to include it with your command, you need to remove the square brackets. PennNames variables should be replaced by the appropriate information. The following PennNames variables are used in these instructions:

Variable   Description   Example
FULLNAME   A person's full name, in "last, first middle" format.   Smith, John H
ID   A person's PennID number or SSN. We strongly advise using the PennID when possible and avoid using the SSN.   PennID - 10000011
SSN - 9998887777
MAX   Maximum number of PennNames to generate. May return fewer depending on availability. Will never return more than 50 in any case.   15
PENNNAME   A username with a minimum of two characters, a maximum of eight characters, all lowercase and alphanumeric. The first character must be an alpha. Special characters and punctuation are not permitted.   joeuser
SEED   A character string used to generate a list of available PennNames. Useful when trying to assign a PennName that is not based on the fullname of the person.   superman
SPONSOR   A PennNames sponsor.   PennKey
STATUS   Status of a PennName or a PennName sponsorship. The status of a PennName displays when using the id2name with the "all" option. The status of a PennName sponsorship displays when using the name2id with the "all" option.   Possible statuses are:
AActive
EExpired
HHeld
NRenamed
RReserved
ORADB   Which PennCommunity Oracle database to use for a session.   penncard
S2   Additional status information for a PennName. For internal use only.   ---
TIME   Timestamp indicating last activity for a PennName. Timestamps display when using the id2name and name2id with the "all" option. The format is: YYYY-MM-DD, the letter "T', and hh:mm:ss.   2004-07-13T11:39:47



Invoking the client

After obtaining the PennNames client (for unix or windows) and installing it on a registered host, you can invoke the PennNames client from the UNIX commandline or from within a script.

The format of calling the PennNames client is

pennnames [-t] [-p path-to-passwd] PennNames-command ...

Please note that any arguments to the PennNames client must preceed the PennName command.



Optional commandline arguments

The PennNames client takes optional commandline arguments:

Argument   Description
-t   Specifies that the PennNames client should use the test server as defined in defines.h
#define TESTSERVER "pennnames-test.upenn.edu"
rather than using the production PennNames server, pennnames.upenn.edu.
-p path-to-password   Specifies an alternate location for the PennNames password. By default, the PennNames client will use the password file as defined in defines.h
#define DEFPWFILE "/usr/local/etc/pennnames.pw"
This argument is useful if you have multiple PennNames sponsors. You can store your second sponsor password in a second file and use the -p argument when calling the PennNames client on behalf of your second sponsor. The alternate file, like the default password file, should only be accessed by people and programs authorized to create accounts on your system.



PennNames commands

The following commands are available for the PennNames client:

Before issuing any PennNames client action commands, you must first get a session ID, <SID>. Except where noted, your <SID> remains active until you issue the PennNames client quit or if there is 15 minutes of inactivity and you can issue multiple PennNames action commands while your <SID> is alive. It is a good practice to quit your sessions.

If a PennNames command takes an <ID> as an argument, there are three versions of that command. For example, add can be called as: add, pennid_add, or ssn_add. If you use the plain version of the command, that command can take either a PennID or an SSN as the <ID>. If you specifically use pennid_add, the <ID> argument must be a PennID and if you use ssn_add, the <ID> argument must be a SSN. As usual, we advise that you use the PennID when possible and avoid using the SSN.

All output has the following format: a three digit result code, a dash or space, and a human readable result. A space indicates that this is the last line of output, a dash means that more output is coming. This is an artifact of the communications between the client and the server; if you are using the PennNames client from within a script, you can simply read to end of file and ignore the spaces/dashes. Use regular expressions to test for the expected output. For example, in a perl script, your test may be something like

if ($returncode =~ /^203( |-)/) ...

Command Response Synopsis
pennnames session [<ORADB>]


Examples:

pennnames session

pennnames session tcom

201 Success <SID> Creates a session ID, using the default Oracle database (penncard on the production server, tcom on test) for PennCommunity unless is specified. You must obtain a new session ID for each new person or PennName added. The session expires 15 minutes after the last command run for that or if you quit the session. The refresh command is available to extend the life of a session.

The followed values of are valid for production and test servers: penncard (synonymous with pcom, also pncd), tcom and dcom.

pennnames refresh <SID>


Example:
pennnames refresh H00012349
201 Success <SID> Refresh the <SID>. Resets the time to live for a <SID> and extends the life of the <SID> for 15 minutes.
pennnames quit <SID>


Example:
pennnames quit H00012349
201 Success <SID> End this session, freeing all names held as a result of the hold or generate commands.

NOTE: Since add also ends the session, quit is provided for sessions in which add is not used.
pennnames add <SID> <PENNNAME> <ID>
pennnames pennid_add <SID> <PENNNAME> <ID>
pennnames ssn_add <SID> <PENNNAME> <ID>


Example:
pennnames add H00012349 bozo 12345678
201 Success <SID> Register your sponsorship for this PennName/ID. You can only add sponsorships for a person who has a PennID and you should add your sponsorship even if the PennName is already registered to that person.

NOTE: this command closes the session (a side effect of freeing all held names for the session). quit is unnecessary after an add Use add as the last command in the session.
pennnames fullname <SID> <ID>
pennnames pennid_fullname <SID> <ID>
pennnames ssn_fullname <SID> <ID>


Example:
pennnames fullname H00012349 12345678
204 Success <SID> <ID> <FULLNAME> Extracts the fullname associated with the <ID> from PennCommunity.
pennnames generate <SID> <MAX> <ID>
   [<FULLNAME>] [:<SEED>]
pennnames ssn_generate <SID> <MAX> <ID>
   [<FULLNAME>] [:<SEED>]
pennnames pennid_generate <SID> <MAX> <ID>
   [<FULLNAME>] [:<SEED>]



Example:
pennnames generate H00012349 15 12345678 Joe User :bozo
202-Success <SID> <FULLNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
Generates a list of available PennNames for a person. If the user already has a PennName, only that PennName will be generated. If the user doesn't already have a PennName, a list of possible available PennNames will be generated up to but no more than the <MAX> specified. If the user does not have a persistent affiliation in the central data stores, generate will only return the next available guest PennName. A guest PennName starts with the letter "g" and is followed by 7 digits, e.g., "g1234567".

When generating a list, generate will extract the full name of the person from the central data stores and use that as a basis for the list of possible PennNames. If you enter an optional full name, generate will also use the full name that you supply as a basis for this list of possible PennNames. Entering an optional full name is helpful in those cases where a person may use a name that differs from the official name on record.

To further customize the list of possible PennNames that are generated, you can add your own string, the <SEED>, that will be used in the algorithm to generate a list of possible PennNames. Please note that if you opt to give a <SEED>, that string of characters must be preceeded by a colon. PennNames that start with either the letter "g" or the letter "n" followed by 7 digits are a special class and will not be included in the generate list. If your <SEED> is something like "g1234567" it will be ignored when creating a list of generated PennnNames.
pennnames hold <SID> <PENNNAME>
   [<ID>]



Example:
pennnames hold H00012349 bozo 12345678
201 Success <SID> Hold this PennName for fifteen minutes or until you quit the session. Useful if you want to generate your own list of choices. The names will be held until the session expires.

If you opt to hold a <PENNNAME> and also include an <ID> as argument to the command, the <PENNNAME> will be held for that <ID> for 3 days. The <ID> must be a PennID.
pennnames id2name <SID> <ID>
   [all]
pennnames ssn_id2name <SID> <ID>
   [all]
pennnames pennid_id2name <SID> <ID>
   [all]



Example:
pennnames id2name H00012349 12345678 all
203-Success <SID>
203 <PENNNAME>

With all argument:
203-Success <SID>
203-<PENNNAME>
299-<PENNNAME> <ID> <STATUS>/<S2> <TIME>
299-<PENNNAME> <ID> <STATUS>/<S2> <TIME>
299 <PENNNAME> <ID> <STATUS>/<S2> <TIME>
Returns the one active <PENNNAME> associated with the <ID>.

If no name is registered for that ID, id2name returns error 508.

If you opt to use the "all" argument, you will also get a full list of all PennNames associated with that <ID> including inactive <PENNNAME>s or held <PENNNAME>s.
pennnames name2id <SID> <PENNNAME>
   [all]



Example:
pennnames name2id H00012349 bozo all
205-Success <SID>
205-<ID>
205-Sponsor-<SPONSOR>
205-Sponsor-<SPONSOR>
205-Sponsor-<SPONSOR>
205-Sponsor-<SPONSOR>
205 Success <SID>

With all argument:
205-Success <SID>
299-<ID> <STATUS>/<S2> <TIME>
299-Sponsor-<SPONSOR> <STATUS> <TIME>
299-Sponsor-<SPONSOR> <STATUS> <TIME>
299-Sponsor-<SPONSOR> <STATUS> <TIME>
299 Sponsor-<SPONSOR> <STATUS> <TIME>
Checks to see if the specified PennName has been registered Returns a list of the PennID associated with that name and the sponsors for which the PennID and PennName have been registered.

If the name is not an active PennName, name2id returns error 508.

If you opt to use the "all" argument, your list will also include the sponsor <STATUS>, either "A(ctive" or "E(xpired)" and the timestamp of the last activity by that sponsor.
pennnames regenerate <SID> <MAX> <ID>
   [<FULLNAME>] [:<SEED>]
pennnames ssn_regenerate <SID> <MAX> <ID>
   [<FULLNAME>] [:<SEED>]
pennnames pennid_regenerate <SID> <MAX> <ID>
   [<FULLNAME>] [:<SEED>]



Example:
pennnames regenerate H00012349 15 12345678 Joe User :bozo
202-Success <SID> <FULLNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
202-<PENNNAME>
Regenerate acts just like the generate command except that it is used to generate a new list of PennNames for a user who already has a PennName. If you use the generate command for a user who already has a PennName, generate will only return the one PennName already assigned to that user. In situations where you may need to rename a PennName, you can use regenerate to generate a new list of possible PennNames for the user who already has a PennName.
pennnames relinquish <SID> <PENNNAME> <ID>
pennnames pennid_relinquish <SID> <PENNNAME> <ID>
pennnames ssn_relinquish <SID> <PENNNAME> <ID>



Example:
pennnames relinquish H00012349 bozo 12345678
203 Success deleted 1 sponsors,
    0 names

203 Success deleted 1 sponsors,
    1 names

The relinquish command enables a sponsor to remove its sponsorship for an active PennName. If your sponsorship is the last sponsorship for a PennName, that PennName is then flagged as "E(xpired)".
pennnames reserve <SID> <PENNNAME>


Example:
pennnames reserve H00012349 admin
201 Success <SID> Add a PennName as a reserved PennName, such as "root". Used to reserve PennNames for non-humans so that they will not be assigned to individuals as a PennName although a reserved PennName is then available to be used by any other system on campus for other non-human situations. You may want to periodically go through all of your mail aliases and reserve them using this API.



Error codes

Possible error codes returned by the server:
  • 500 Command unrecognized
  • 501 Syntax error
  • 502 Invalid session identifier <SID>
  • 503 Password not recognized
  • 504 PennName <PENNNAME> in use
  • 505 ID <ID> in use
  • 506 ID <ID> not in PennCommunity database
  • 507 Badly formatted PennName <PENNNAME>
  • 508 ID <ID> not found
  • 508 PennName <PENNNAME> not found
  • 509 Badly formatted ID <ID>
  • 510 PennName <PENNNAME> is reserved
  • 550 Internal error
  • 551 Database error
  • 552 Database not found
  • 560 Oracle Database error
  • 561 Could not get SSN for PennID <ID>
  • 562 Could not get PennID for SSN <ID>
  • 570 No sponsors match your request"
top

Information Systems and Computing
University of Pennsylvania
Comments & Questions


Penn Computing University of Pennsylvania
Information Systems and Computing, University of Pennsylvania