=========================================================================
How to use the TGrid/TAlien/TAlienFile class V1.1 - Andreas.Peters@cern.ch
=========================================================================


TGrid-Plugin: TAlien
====================

To connect to Alien you have to connect to a running API service of your
virtual organization.

Creating <gGrid> instance:
a) // connecting to an API service 

    TGrid::Connect("alien://pcapiserv01.cern.ch:9000","aliprod);
    
    // connecting to an API service which is defined already by the
    environement variables:
		 export alien_API_HOST=...
		 export alien_API_PORT=...
		 export alien_API_USER=...
    TGrid::Connect("alien://");

    // connect to an API service with an authentication token established
    previously with gShellq.

b)  TGrid::Connect("alien://",0,0,"t");

    In case a) the authentication is private to the process, while case b)
    shares the authentication(session) with the shell, which has established
    the session previously. Notice that a) is not thread-safe, while b) is!

If you have executed TGrid::Connect(), the gGrid global variable
should be set != 0.

Some examples:

- change the working directory
  
    gGrid->Cd("/alice/");  // => returns 1 for success, 0 for error
  
- get the working directory
  
    printf("GRID Working is %d",gGrid->Pwd());

- list a directory

    TGridResult* result = gGrid->Ls("/alice");                         
    Int_t i=0;                                                         
    while (result->GetFileName(i))                                    
      printf("File %s\n",result->GetFileName(i++));
    TGridResult* result = gGrid->Ls("/alice");                         
    Int_t i=0;                                                           
    while (result->GetFileName(i))                                    
      printf("File %s\n",result->GetFileName(i++));

- get all file permissions - using the GetKey function

    TGridResult* result = gGrid->Ls("/alice","-la");                   
    while (result->GetFileName(i))\                                    
    printf("The permissions are %s\n",result->GetKey(i++,"permissions")  
                                                                       
    // => the defined keys for GetKey can be seen using result->Print();   


- query files under a certain namespace tree

    TGridResult* result = gGrid->Query("/alice/,"*.root");


You can execute any existing command via the Command interface:
    
    TGridResult* result = gGrid->Command("ls -la /",0,2); 

    // '0' switches of the output of stdout and stderr to the terminal
    // '2' selects the result stream to be returned as TGridResult* :
	  '0' returns stdout, 
	  '1' returns stderr,
	  '2' returns the result structure

-> This command is equivalent to:
   
    gGrid->Ls("/","-la");

You can print the stdout of the last command via:
    gGrid->Stdout();

You can print the stderr of the last command via:
    gGrid->Stderr();
        
To see the result structure of a command, you can just use the 'Print' function for the
TGridResult:

	result->Print();



TFile-Plugin: TAlienFile
========================

Files stored in Alien can be opened with the catalogue LFN or a GUID.
To open a file by LFN use:

	TFile* myfile = TFile::Open("alien:///alice/cern.ch/file.root");

or
	
	TFile* myfile = TFile::Open("/alien/alice/cern.ch/file.root");
	

To open a file by GUID use:

	TFile* myfile = TFile::Open("alien://<guid>");

To address a certain storage element add to the URL
	   "?se=ALICE::CERN::Castor";

f.e.    TFile::Open("/alien/alice/cern.ch/file.root?se=ALICE::CERN::Castor");


To open a ZIP file in an archive, use:

	TFile::Open("/alien7alice/cern.ch/archivefile.zip#file.root");

- this assumes, that archivefile.zip is an UNCOMPRESSED zip archive containing
  'file.root'.
- remember, that archives need to have the suffix '.zip' to be understood as
  such.